SimBrief Flight Planning MCP Server

A Model Context Protocol (MCP) server that provides access to SimBrief flight planning data for Claude Desktop and other MCP clients. Built with TypeScript, deployed on Cloudflare Workers with Google OAuth authentication.

Features

• Google OAuth Authentication: Secure access control with email-based permissions
• Cloudflare Workers: Edge deployment with Durable Objects for stateful sessions
• SSE/HTTP Transports: Dual protocol support for MCP clients
• SimBrief API Integration: Complete access to flight planning data
• TypeScript: Full type safety and modern async/await patterns
• Sentry Integration: Optional error tracking and performance monitoring
• Rate Limit Optimization: Optional API key support for improved SimBrief rate limits

Available MCP Tools

Flight Plan Tools

1. getLatestFlightPlan (Preferred/Default)

   • Get complete JSON data for your latest flight plan
   • Includes all details: NOTAMs, weather, crew alerts, MEL/CDL, etc.
   • Use by default unless user specifically asks for a summary

2. getFlightPlanById

   • Get complete JSON data for a specific flight plan by ID
   • Requires 21-character SimBrief plan ID

3. getDispatchBriefing

   • Get formatted dispatch briefing with operational information
   • Includes: flight info, route, fuel planning, weights, weather

4. getLatestFlightPlanSummary

   • Get summary of latest flight plan
   • Use only if user specifically requests a summary

5. getFlightPlanByIdSummary

   • Get summary of specific flight plan by ID

Installation

Prerequisites

• Node.js 18 or higher
• npm or yarn
• Cloudflare account
• SimBrief account and User ID
• Google OAuth credentials

Setup

1. Clone the repository:

cd simbrief-mcp

2. Install dependencies:

npm install

3. Configure Wrangler:

Edit wrangler.toml to set your KV namespace ID:

[[kv_namespaces]]
binding = "OAUTH_KV"
id = "your-kv-namespace-id"  # Replace with your actual KV namespace ID

4. Set up secrets:

# Required secrets
wrangler secret put GOOGLE_CLIENT_ID
wrangler secret put GOOGLE_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY

# Optional secrets
wrangler secret put SIMBRIEF_API_KEY  # Improves rate limits
wrangler secret put SENTRY_DSN        # Error tracking

To generate a COOKIE_ENCRYPTION_KEY:

openssl rand -base64 32

5. Configure allowed users:

Edit src/config/allowed-users.ts and add your email username (part before @):

const ALLOWED_USERNAMES = new Set<string>([
  'your-username',  // For your-username@gmail.com
]);

6. Get your SimBrief User ID:
   • Log in to SimBrief (https://www.simbrief.com)
   • Go to Account Settings
   • Find your Pilot ID (this is your User ID)

Development

Local Development

# Start local development server (port 8794)
npm run dev

# Type checking
npm run type-check

# Generate Cloudflare types
npm run cf-typegen

Building

npm run build

Deployment

npm run deploy

Claude Desktop Integration

Local Development Configuration

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "simbrief": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8794/mcp"],
      "env": {}
    }
  }
}

Production Configuration

{
  "mcpServers": {
    "simbrief": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-worker.workers.dev/mcp"],
      "env": {}
    }
  }
}

Replace your-worker.workers.dev with your actual Cloudflare Workers domain.

Usage Examples

Get Latest Flight Plan

Ask Claude:

"Get my latest SimBrief flight plan for user ID 123456"

Get Dispatch Briefing

Ask Claude:

"Get dispatch briefing for my latest flight plan (user ID 123456)"

Get Specific Flight Plan

Ask Claude:

"Get flight plan ABCDEF123456789012345 for user 123456"

Project Structure

simbrief-mcp/
├── src/
│   ├── auth/
│   │   ├── google-handler.ts       # Google OAuth flow
│   │   └── oauth-utils.ts          # OAuth utilities
│   ├── config/
│   │   └── allowed-users.ts        # User access control
│   ├── tools/
│   │   ├── simbrief-api.ts         # SimBrief API client
│   │   └── register-simbrief-tools.ts  # MCP tools registration
│   ├── types/
│   │   └── index.ts                # TypeScript types
│   └── index.ts                    # Main entry point
├── wrangler.toml                   # Cloudflare Workers config
├── tsconfig.json                   # TypeScript config
├── package.json                    # Dependencies
└── README.md                       # This file

Environment Variables

Required Secrets

• GOOGLE_CLIENT_ID: Google OAuth client ID
• GOOGLE_CLIENT_SECRET: Google OAuth client secret
• COOKIE_ENCRYPTION_KEY: 32-character random string for cookie signing

Optional Secrets

• SIMBRIEF_API_KEY: SimBrief API key for improved rate limits
• SENTRY_DSN: Sentry DSN for error tracking
• ENVIRONMENT: Environment name (defaults to "production")

Security Features

• OAuth 2.0: Google authentication with email verification
• HMAC Cookies: Signed cookies for client approval persistence
• Access Control: Email-based user allowlist
• Error Sanitization: Sensitive information removed from errors
• Edge Security: Cloudflare Workers security features

Monitoring

• Console Logs: Available in Cloudflare dashboard
• Sentry Integration: Optional error tracking and performance monitoring
• Cloudflare Analytics: Built-in request metrics

Troubleshooting

Configuration Issues

Problem: Cannot find SimBrief User ID

Solution:

1. Log in to SimBrief
2. Go to Account Settings
3. Your Pilot ID is your User ID

Authentication Issues

Problem: "Access Denied" error

Solution:

• Check that your email username is in src/config/allowed-users.ts
• Verify Google OAuth credentials are set correctly

API Errors

Problem: "SimBrief API error" messages

Solution:

1. Verify User ID is correct
2. Check if you have recent flight plans on SimBrief
3. If using API key, ensure it's valid

Differences from Original Python Version

Improvements

1. TypeScript: Full type safety and better IDE support
2. Cloudflare Workers: Edge deployment for global low latency
3. Google OAuth: Secure authentication instead of public access
4. Better Error Handling: Comprehensive error messages with Sentry integration
5. Code Organization: Modular structure with clear separation of concerns
6. Production Ready: Built-in monitoring, logging, and security features

Migration Notes

If you're migrating from the Python version:

1. User ID is still passed as a parameter (not environment variable)
2. All tool names follow camelCase convention (getLatestFlightPlan vs get_latest_flight_plan)
3. Requires Google authentication - set up allowed users
4. Deployed on Cloudflare Workers instead of running locally

Contributing

Contributions are welcome! Please ensure:

1. Code follows TypeScript and Prettier formatting
2. All tools include proper error handling
3. Documentation is updated for new features
4. Tests pass (if applicable)

License

MIT

Support

For issues or questions:

• Check the troubleshooting section above
• Review Cloudflare Workers logs
• Check Sentry for error details (if configured)

Credits

Built with:

• Model Context Protocol SDK
• Cloudflare Workers
• SimBrief API