Schwab MCP

🚀 Schwab MCP Server

This is a Model Context Protocol (MCP) server that allows AI assistants like Claude to securely interact with Charles Schwab accounts and market data through the official Schwab API.

🚀 Quick Start

Prerequisites

1. Schwab Developer Account: Register at Schwab Developer Portal.
2. Cloudflare Account: Required for deployment. A Workers paid plan is needed for Durable Objects.
3. Node.js: Version 22.x or higher.
4. Wrangler CLI: Installed via npm (included in dev dependencies).

Quick Setup

git clone <repository-url>
cd schwab-mcp
npm install

# Authenticate with Cloudflare (first time only)
npx wrangler login

# Create KV namespace for OAuth token storage
npx wrangler kv:namespace create "OAUTH_KV"
# Note the ID from the output - you'll need it for configuration

# Set up your personal configuration
cp wrangler.example.jsonc wrangler.jsonc
# Edit wrangler.jsonc to:
# 1. Replace YOUR_KV_NAMESPACE_ID_HERE with the ID from above
# 2. Change the name to something unique (e.g., "schwab-mcp-yourname")

# Set your secrets
npx wrangler secret put SCHWAB_CLIENT_ID      # Your Schwab App Key
npx wrangler secret put SCHWAB_CLIENT_SECRET  # Your Schwab App Secret
npx wrangler secret put SCHWAB_REDIRECT_URI   # https://your-worker-name.workers.dev/callback
npx wrangler secret put COOKIE_ENCRYPTION_KEY # Generate with: openssl rand -hex 32

# Deploy
npm run deploy

Configuration Notes

• wrangler.example.jsonc - Template configuration (committed).
• wrangler.jsonc - Your personal config (git-ignored, created from template).
• .dev.vars - Local development secrets (git-ignored, optional).

Since wrangler.jsonc is git-ignored, you can safely develop and test with your personal configuration without exposing secrets.

Detailed Configuration

1. Create a Schwab App

1. Log in to the Schwab Developer Portal.
2. Create a new app with:
   • App Name: Your MCP server name.
   • Callback URL: https://schwab-mcp.<your-subdomain>.workers.dev/callback.
   • App Type: Personal or third-party based on your use case.
3. Note your App Key (Client ID) and generate an App Secret.

2. Set Environment Variables

The same secrets from Quick Setup need to be set (see above).

GitHub Actions Deployment

For automated deployments, add these GitHub repository secrets:

1. CLOUDFLARE_API_TOKEN: Your Cloudflare API token.
2. OAUTH_KV_ID: Your KV namespace ID.

The workflow handles validation and deployment when pushing to main. Cloudflare secrets must still be set via wrangler secret.

Testing with Inspector

Test your deployment using the MCP Inspector:

npx @modelcontextprotocol/inspector@latest

Enter https://schwab-mcp.<your-subdomain>.workers.dev/sse and connect. You'll be prompted to authenticate with Schwab.

✨ Features

Trading Tools

• Account Management
  • getAccounts: Retrieve all account information with positions and balances.
  • getAccountNumbers: Get list of account identifiers.
• Order Management
  • getOrder: Get order by ID.
  • getOrders: Fetch orders with filtering by status, time range, and symbol.
  • getOrdersByAccountNumber: Get orders by account number.
  • cancelOrder: Cancel an order (Experimental).
  • placeOrder: Place an order (Experimental).
  • replaceOrder: Replace an order (Experimental).
• Market Quotes
  • getQuotes: Get real-time quotes for multiple symbols.
  • getQuoteBySymbolId: Get detailed quote for a single symbol.
• Transaction History
  • getTransactions: Retrieve transaction history across all accounts with date filtering.
• User Preferences
  • getUserPreference: Retrieve user trading preferences and settings.

Market Data Tools

• Instrument Search
  • searchInstruments: Search for securities by symbol with fundamental/reference data.
• Price History
  • getPriceHistory: Get historical price data with customizable periods and frequencies.
• Market Hours
  • getMarketHours: Check market operating hours by date.
  • getMarketHoursByMarketId: Get specific market information.
• Market Movers
  • getMovers: Find top market movers by index ($SPX, $COMPX, $DJI).
• Options Chains
  • getOptionChain: Retrieve full options chain data with Greeks.
  • getOptionExpirationChain: Get option expiration dates.

💻 Usage Examples

Claude Desktop Configuration

1. Use Claude Integrations

1. Go to the Claude Desktop settings.
2. Click on the "Integrations" tab.
3. Click on the "Add Custom Integration" button.
4. Enter the integration name "Schwab".
5. Enter the MCP Server URL: https://schwab-mcp.<your-subdomain>.workers.dev/sse.
6. Click on the "Add" button.
7. Click "Connect" and the Schwab Authentication flow will start.

2. Add the MCP Server to your Claude Desktop configuration

Add the following to your Claude Desktop configuration file:

{
    "mcpServers": {
        "schwab": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://schwab-mcp.<your-subdomain>.workers.dev/sse"
            ]
        }
    }
}

Restart Claude Desktop. When you first use a Schwab tool, a browser window will open for authentication.

Example Commands

Once connected, you can ask Claude to:

• "Show me my Schwab account balances".
• "Get a quote for AAPL".
• "What are today's market movers in the $SPX?".
• "Show me the options chain for TSLA".
• "Get my recent transactions from the last week".

Local Development

For local development, create a .dev.vars file (automatically ignored by git):

SCHWAB_CLIENT_ID=your_development_app_key
SCHWAB_CLIENT_SECRET=your_development_app_secret
SCHWAB_REDIRECT_URI=http://localhost:8788/callback
COOKIE_ENCRYPTION_KEY=your_random_key_here
LOG_LEVEL=DEBUG  # Optional: Enable debug logging

Run locally:

npm run dev
# Server will be available at http://localhost:8788

Connect to http://localhost:8788/sse using the MCP Inspector for testing.

📚 Documentation

Overview

This MCP server acts as a bridge between AI assistants and the Schwab API, providing:

• Secure OAuth Authentication: Implements Schwab's OAuth 2.0 flow with PKCE for secure authentication.
• Comprehensive Trading Tools: Access to accounts, orders, quotes, and transactions.
• Market Data Tools: Real-time quotes, price history, market hours, movers, and options chains.
• Account Privacy: Built-in account identifier scrubbing to protect sensitive information.
• Enterprise-Ready: Deployed on Cloudflare Workers with Durable Objects for state management.

Architecture

Technology Stack

• Runtime: Cloudflare Workers with Durable Objects.
• Authentication: OAuth 2.0 with PKCE via @cloudflare/workers-oauth-provider.
• API Client: @sudowealth/schwab-api for type-safe Schwab API access.
• MCP Framework: @modelcontextprotocol/sdk with workers-mcp adapter.
• State Management: KV storage for tokens, Durable Objects for session state.

Security Features

1. OAuth 2.0 with PKCE: Secure authentication flow preventing authorization code interception.
2. Enhanced Token Management:
   • Centralized KV token store with automatic migration.
   • Automatic token refresh (5 minutes before expiration).
   • 31-day token persistence with TTL.
3. Account Scrubbing: Sensitive account identifiers are automatically replaced with display names.
4. State Security: HMAC-SHA256 signatures for state parameter integrity.
5. Cookie Encryption: Client approval state encrypted with AES-256.
6. Secret Redaction: Automatic masking of sensitive data in logs.

Development

Available Scripts

npm run dev          # Start development server on port 8788
npm run deploy       # Deploy to Cloudflare Workers
npm run typecheck    # Run TypeScript type checking
npm run lint         # Run ESLint with automatic fixes
npm run format       # Format code with Prettier
npm run validate     # Run typecheck and lint together

Debugging

The server includes comprehensive logging with configurable levels:

• Development: Terminal output with colored logs.
• Production: Cloudflare dashboard → Workers → Logs.
• Log Levels: DEBUG, INFO, WARN, ERROR (set via LOG_LEVEL env var).

Enable debug logging to see detailed OAuth flow and API interactions:

# For local development
echo "LOG_LEVEL=DEBUG" >> .dev.vars

# For production
npx wrangler secret put LOG_LEVEL --secret="DEBUG"

Error Handling

The server implements robust error handling with specific error types:

• Authentication Errors (401): Prompt for re-authentication.
• Client Errors (400): Invalid parameters, missing data.
• Server Errors (500): API failures, configuration issues.
• Network Errors (503): Automatic retry with backoff.
• All errors include request IDs for Schwab API troubleshooting.

Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

📄 License

MIT

Troubleshooting

Common Issues

1. "KV namespace not found" error
   • Ensure you created the KV namespace and updated wrangler.jsonc.
   • Run npx wrangler kv:namespace list to verify.
2. Authentication failures
   • Verify your redirect URI matches exactly in Schwab app settings.
   • Check that all secrets are set correctly with npx wrangler secret list.
   • Enable debug logging to see detailed OAuth flow.
3. "Durable Objects not available" error
   • Ensure you have a paid Cloudflare Workers plan.
   • Durable Objects are not available on the free tier.
4. Token refresh issues
   • The server automatically refreshes tokens 5 minutes before expiration.
   • Tokens are migrated from clientId to schwabUserId keys automatically.
   • Check KV namespace for stored tokens: npx wrangler kv:key list --namespace-id=<your-id>.

Recent Updates

• Enhanced Token Management: Centralized KV token store prevents token divergence.
• Improved Security: HMAC-SHA256 state validation and automatic secret redaction.
• Better Error Handling: Structured error types with Schwab API error mapping.
• Configurable Logging: Debug mode for troubleshooting OAuth and API issues.

Acknowledgments

• Built with Cloudflare Workers.
• Uses Model Context Protocol.
• Powered by @sudowealth/schwab-api.

⚠️ Important Note

This is an unofficial, community-developed TypeScript MCP server for Charles Schwab. It has not been approved, endorsed, or certified by Charles Schwab. It is provided as-is, and its functionality may be incomplete or unstable. Use at your own risk, especially when dealing with financial data or transactions.