Schwab MCP Server

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

What You Can Do

Ask Claude to:

"Show me my Schwab account balances and positions"
"Get real-time quotes for AAPL, GOOGL, and MSFT"
"What are today's market movers in the $SPX?"
"Show me the options chain for TSLA with Greeks"
"Get my transactions from the last 30 days"
"Search for ETFs related to technology"
"Check if the markets are open"

Unofficial MCP Server

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.

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

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

Prerequisites

Schwab Developer Account: Register at Schwab Developer Portal
Cloudflare Account: For deployment (Workers paid plan required for Durable Objects)
Node.js: Version 22.x or higher
Wrangler CLI: Installed via npm (included in dev dependencies)

Getting Started

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

Log in to the Schwab Developer Portal
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
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:

CLOUDFLARE_API_TOKEN: Your Cloudflare API token
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.

Usage

Claude Desktop Configuration

1. Use Claude Integrations

Go to the Claude Desktop settings
Click on the "Integrations" tab
Click on the "Add Custom Integration" button
Enter the integration name "Schwab"
Enter the MCP Server URL: https://schwab-mcp.<your-subdomain>.workers.dev/sse
Click on the "Add" button
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.

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

OAuth 2.0 with PKCE: Secure authentication flow preventing authorization code interception
Enhanced Token Management:
- Centralized KV token store with automatic migration
- Automatic token refresh (5 minutes before expiration)
- 31-day token persistence with TTL
Account Scrubbing: Sensitive account identifiers are automatically replaced with display names
State Security: HMAC-SHA256 signatures for state parameter integrity
Cookie Encryption: Client approval state encrypted with AES-256
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

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

License

MIT

Troubleshooting

Common Issues

"KV namespace not found" error
- Ensure you created the KV namespace and updated wrangler.jsonc
- Run npx wrangler kv:namespace list to verify
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
"Durable Objects not available" error
- Ensure you have a paid Cloudflare Workers plan
- Durable Objects are not available on the free tier
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