schwab-mcp

# 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 - **Local-Only**: Runs entirely on your machine with local HTTPS server and file-based token storage ## 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 1. **Schwab Developer Account**: Register at [Schwab Developer Portal](https://developer.schwab.com) 2. **Node.js**: Version 20.x or higher (22.x recommended) ## Getting Started ### Quick Setup ```bash git clone <repository-url> cd schwab-mcp npm install # Configure your environment cp .env.example .env # Edit .env with your Schwab app credentials # Start the MCP server (will prompt for OAuth on first run) npm run start ``` ### Configuration #### 1. Create a Schwab App 1. Log in to the [Schwab Developer Portal](https://developer.schwab.com) 2. Create a new app with: - **App Name**: Your MCP server name (e.g., "My Schwab MCP") - **Callback URL**: `https://localhost:3000/callback` - **App Type**: Personal 3. Note your **App Key** (Client ID) and generate an **App Secret** #### 2. Configure Environment Variables Copy the `.env.example` file to `.env` and fill in your credentials: ```bash cp .env.example .env ``` Edit `.env`: ```env # Schwab OAuth Configuration SCHWAB_CLIENT_ID=your_schwab_app_key_here SCHWAB_CLIENT_SECRET=your_schwab_app_secret_here # OAuth Redirect URI (must match what you configured in Schwab Developer Portal) SCHWAB_REDIRECT_URI=https://localhost:3000/callback # Optional: Port for HTTPS server (default: 3000) PORT=3000 # Optional: Log level (trace, debug, info, warn, error, fatal) LOG_LEVEL=info # Optional: Environment (development, staging, production) ENVIRONMENT=production ``` #### 3. First Run - OAuth Authentication On the first run, the server will: 1. Generate self-signed certificates in `.certs/` directory (no OpenSSL required) 2. Start an HTTPS server on `https://localhost:3000` 3. Open your browser to the Schwab authorization page 4. After you authorize, tokens will be saved to `.auth/` directory 5. The MCP server will start and be ready to use ```bash npm run start ``` **Note**: You may need to trust the self-signed certificate in your browser or system. The certificate is only used for localhost OAuth callback and is generated automatically using Node.js crypto libraries. ## Usage ### Claude Desktop Configuration Add the server to your Claude Desktop configuration file: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "schwab": { "command": "npx", "args": [ "tsx", "/path/to/schwab-mcp/src/index.ts" ], "env": { "SCHWAB_CLIENT_ID": "your_app_key", "SCHWAB_CLIENT_SECRET": "your_app_secret", "SCHWAB_REDIRECT_URI": "https://localhost:3000/callback" } } } } ``` Or if you prefer to build first and run the compiled JavaScript: ```json { "mcpServers": { "schwab": { "command": "node", "args": [ "/path/to/schwab-mcp/dist/index.js" ], "env": { "SCHWAB_CLIENT_ID": "your_app_key", "SCHWAB_CLIENT_SECRET": "your_app_secret", "SCHWAB_REDIRECT_URI": "https://localhost:3000/callback" } } } } ``` Note: The first option using `tsx` is recommended as it doesn't require a build step. Restart Claude Desktop. The server will connect via stdio transport. ### 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" ## Architecture ### Technology Stack - **Runtime**: Node.js with TypeScript - **Authentication**: OAuth 2.0 with PKCE via `@sudowealth/schwab-api` - **API Client**: `@sudowealth/schwab-api` for type-safe Schwab API access - **MCP Framework**: `@modelcontextprotocol/sdk` with stdio transport - **State Management**: File-based token storage in `.auth/` directory - **OAuth Server**: Express with HTTPS for OAuth callback handling ### Security Features 1. **OAuth 2.0 with PKCE**: Secure authentication flow preventing authorization code interception 2. **Local Token Storage**: Tokens stored locally in `.auth/` directory (never sent to external servers) 3. **HTTPS Localhost**: Self-signed certificates for secure OAuth callback 4. **Automatic Token Refresh**: Tokens refreshed 5 minutes before expiration 5. **Account Scrubbing**: Sensitive account identifiers automatically replaced with display names 6. **Secret Redaction**: Automatic masking of sensitive data in logs ## Development ### Available Scripts ```bash npm run start # Start the MCP server npm run dev # Start in development mode (same as start) npm run build # Build TypeScript to JavaScript npm run typecheck # Run TypeScript type checking npm run lint # Run ESLint npm run format # Format code with Prettier npm run validate # Run typecheck and lint together ``` ### Project Structure ``` schwab-mcp/ ├── .auth/ # OAuth tokens (git-ignored) ├── .certs/ # Self-signed certificates (git-ignored) ├── src/ │ ├── index.ts # Main MCP server entry point │ ├── auth/ # OAuth authentication client │ ├── server/ # OAuth HTTP server and certificate generation │ ├── shared/ # Shared utilities (logging, token storage) │ └── tools/ # MCP tool implementations ├── .env # Environment variables (git-ignored) └── .env.example # Example environment variables ``` ### Debugging The server includes comprehensive logging with configurable levels: - **Log Levels**: trace, debug, info, warn, error, fatal - Set via `LOG_LEVEL` environment variable in `.env` Enable debug logging to see detailed OAuth flow and API interactions: ```env LOG_LEVEL=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 - 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. **"Certificate error" in browser** - This is expected with self-signed certificates - Accept the certificate warning during OAuth flow - The certificate is only used for `https://localhost:3000/callback` 2. **"Cannot find module" errors** - Run `npm install` to ensure all dependencies are installed - Make sure you're using Node.js 20.x or higher 3. **Authentication failures** - Verify your redirect URI matches exactly: `https://localhost:3000/callback` - Check that your Schwab app credentials are correct in `.env` - Enable debug logging: `LOG_LEVEL=debug` in `.env` 4. **"Port already in use" error** - Change the PORT in `.env` to a different value - Make sure no other process is using port 3000 ## Recent Updates - **Local-Only Architecture**: Migrated from Cloudflare Workers to local Node.js server - **File-Based Token Storage**: Tokens stored securely in local `.auth/` directory - **HTTPS OAuth Flow**: Self-signed certificates for secure localhost OAuth callback - **Stdio Transport**: Uses standard MCP SDK with stdio for Claude Desktop integration ## Acknowledgments - Uses [Model Context Protocol](https://modelcontextprotocol.io/) - Powered by [@sudowealth/schwab-api](https://www.npmjs.com/package/@sudowealth/schwab-api) - Built with [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk)