msfs-mcp-server/README.md

Model Context Protocol server for Microsoft Flight Simulator SimConnect integration

# MSFS SimConnect MCP Server

An MCP (Model Context Protocol) server that provides Claude with tools to read and write data from Microsoft Flight Simulator via SimConnect.

## Features

### 🔌 Connection Management
- Connect to MSFS via SimConnect
- Monitor connection status
- Automatic reconnection with exponential backoff

### 📊 Aircraft Data Reading
- Real-time aircraft position (lat/lon/altitude)
- Flight status (airspeed, heading, vertical speed)
- Engine data (RPM, fuel quantity)
- Comprehensive aircraft data

### 🎛️ Aircraft Controls  
- Set autopilot parameters (altitude, heading, speed)
- Toggle landing gear and flaps
- Send custom events to simulator
- Set transponder codes

### 📡 SimVar Operations
- Read specific simulation variables
- Write to writable simulation variables
- Support for all standard MSFS SimVars

## Installation

```bash
bun install
```

## Usage

⚠️ **Important**: This server must run on Windows (not WSL2) to access SimConnect.

### Start the MCP Server

```bash
# From Windows Command Prompt
cd C:\Users\Michael\msfs-mcp-server
bun run src/index.ts
```

### Using with Claude

Add to your Claude configuration:

```json
{
  "mcpServers": {
    "msfs-simconnect": {
      "command": "bun",
      "args": ["run", "C:/Users/Michael/msfs-mcp-server/src/index.ts"]
    }
  }
}
```

## Available Tools

### Connection Tools
- `connect_to_msfs` - Connect to MSFS
- `get_connection_status` - Check connection status

### Data Reading Tools  
- `get_aircraft_position` - Get lat/lon/altitude
- `get_aircraft_data` - Get comprehensive flight data
- `get_flight_status` - Get speed/heading/altitude
- `get_engine_data` - Get RPM/fuel data

### Control Tools
- `set_autopilot_altitude` - Set AP altitude target
- `set_autopilot_heading` - Set AP heading target  
- `set_autopilot_speed` - Set AP speed target
- `toggle_gear` - Toggle landing gear
- `toggle_flaps` - Control flaps
- `set_transponder` - Set transponder code

### Advanced Tools
- `get_simvar` - Read any SimVar
- `set_simvar` - Write to any writable SimVar
- `send_event` - Send custom events

## Prerequisites

- Microsoft Flight Simulator 2020/2024 running
- Flight loaded (not just main menu)
- Developer Mode enabled (recommended)
- Node.js/Bun installed
- Windows environment (SimConnect limitation)

## Troubleshooting

If connection fails:

1. Ensure MSFS is running with active flight
2. Run from Windows Command Prompt (not WSL2)
3. Check that SimConnect.xml is configured correctly
4. Verify Developer Mode is enabled in MSFS
5. Restart MSFS if SimConnect.xml was modified

## Architecture

Built using proven solutions from extensive SimConnect research:

- **Library**: `node-simconnect` v4.0.0
- **Connection**: Named pipes primary, TCP fallback
- **Data Parsing**: Proper RawBuffer handling
- **Period**: SIM_FRAME for real-time updates
- **Error Handling**: Robust reconnection logic

## Example Usage in Claude

"Connect to MSFS and get the current aircraft position"
"Set autopilot altitude to 5000 feet"  
"Toggle the landing gear"
"Get current flight status"

The MCP server handles all SimConnect complexity, providing Claude with simple, reliable tools for flight simulator integration.