Schwab Model Context Protocol Server

# Schwab Model Context Protocol Server This is a server that implements the Model Context Protocol (MCP) for the Schwab API using [schwab-py](https://github.com/alexgolec/schwab-py) and the MCP [python-sdk](https://github.com/modelcontextprotocol/python-sdk). ## Features - Expose Schwab API functionality through Model Context Protocol - Get account information and positions - Retrieve stock quotes and price history - Get market information and movers - Fetch option chains and expiration data - Access order and transaction history - Comprehensive order building and placement capabilities - Advanced order strategies (OCO, trigger-based, and bracket orders) - Modify account state with special tools (requires `--jesus-take-the-wheel` flag) - Designed to integrate with Large Language Models (LLMs) ## Installation ```bash # Install with all dependencies uv add -e . # Install development dependencies uv add -e .[dev] ``` ## Usage ### Authentication The first step is to authenticate with the Schwab API and generate a token: ```bash # Authenticate and generate a token uv run schwab-mcp auth --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --callback-url YOUR_CALLBACK_URL ``` You can set these credentials through environment variables to avoid typing them each time: - `SCHWAB_CLIENT_ID` - `SCHWAB_CLIENT_SECRET` - `SCHWAB_CALLBACK_URL` (defaults to https://127.0.0.1:8182) By default, the token is saved to `~/.local/share/schwab-mcp/token.yaml` (platform-specific). You can specify a different path: ```bash uv run schwab-mcp auth --token-path /path/to/token.yaml ``` Both yaml and json token formats are supported and will be inferred from the file extension. ### Running the Server After authentication, you can run the server: ```bash # Run the server with default token path uv run schwab-mcp server --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --callback-url YOUR_CALLBACK_URL # Run with a custom token path uv run schwab-mcp server --token-path /path/to/token.json --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --callback-url YOUR_CALLBACK_URL # Run with account modification tools enabled uv run schwab-mcp server --jesus-take-the-wheel --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --callback-url YOUR_CALLBACK_URL ``` Token age is validated - if older than 5 days, you will be prompted to re-authenticate. > **WARNING**: Using the `--jesus-take-the-wheel` flag enables tools that can modify your account state. Use with caution as this allows LLMs to cancel orders and potentially perform other actions that change account state. ## Available Tools The server exposes the following MCP tools: > **Note**: Tools 28-35 require the `--jesus-take-the-wheel` flag as they can modify account state by placing orders. ### Date and Market Information 1. `get_datetime` - Get the current datetime in ISO format 2. `get_market_hours` - Get market hours for a specific market 3. `get_movers` - Get movers for a specific index 4. `get_instruments` - Search for instruments with a specific symbol ### Account Information 5. `get_account_numbers` - Get mapping of account IDs to account hashes 6. `get_accounts` - Get information for all linked Schwab accounts 7. `get_accounts_with_positions` - Get accounts with position information 8. `get_account` - Get information for a specific account 9. `get_account_with_positions` - Get specific account with position information 10. `get_user_preferences` - Get user preferences for all accounts including nicknames ### Orders 11. `get_order` - Get details for a specific order 12. `get_orders` - Get orders for a specific account ### Quotes 13. `get_quotes` - Get quotes for specified symbols ### Price History 14. `get_advanced_price_history` - Get advanced price history for a specific symbol 15. `get_price_history_every_minute` - Get price history with minute frequency 16. `get_price_history_every_five_minutes` - Get price history with five minute frequency 17. `get_price_history_every_ten_minutes` - Get price history with ten minute frequency 18. `get_price_history_every_fifteen_minutes` - Get price history with fifteen minute frequency 19. `get_price_history_every_thirty_minutes` - Get price history with thirty minute frequency 20. `get_price_history_every_day` - Get price history with daily frequency 21. `get_price_history_every_week` - Get price history with weekly frequency ### Options 22. `get_option_chain` - Get option chain for a specific symbol 23. `get_advanced_option_chain` - Get advanced option chain for a specific symbol 24. `get_option_expiration_chain` - Get option expiration information for a symbol ### Transactions 25. `get_transactions` - Get transactions for a specific account 26. `get_transaction` - Get details for a specific transaction ### Account Modification Tools (Requires `--jesus-take-the-wheel` flag) 27. `cancel_order` - Cancel a specific order #### Equity Orders 28. `place_equity_market_order` - Place a market order for a stock or ETF 29. `place_equity_limit_order` - Place a limit order for a stock or ETF 30. `place_equity_stop_order` - Place a stop order for a stock or ETF 31. `place_equity_stop_limit_order` - Place a stop-limit order for a stock or ETF 32. `place_equity_order` - Unified function for placing any equity order type #### Option Orders 33. `create_option_symbol` - Create a properly formatted option symbol from components 34. `place_option_market_order` - Place a market order for an option contract 35. `place_option_limit_order` - Place a limit order for an option contract 36. `place_option_order` - Unified function for placing any option order type #### Complex Order Strategies 37. `place_one_cancels_other_order` - Create an OCO order pair where execution of one cancels the other 38. `place_first_triggers_second_order` - Create a sequence where one order triggers another upon execution 39. `place_bracket_order` - Create a complete strategy with entry order and OCO exit orders ## Security Warning The `--jesus-take-the-wheel` flag enables LLMs to perform actions that can modify your account state, including: - Canceling orders - Placing market, limit, stop, and stop-limit orders - Creating complex order strategies (OCO, trigger-based, and bracket orders) These actions have direct financial implications. Only use this flag in controlled environments and with a complete understanding of the risks involved. Consider testing with small positions or in a paper trading account if available. ## Development ```bash # Type check uv run pyright # Format code uv run ruff format . # Lint uv run ruff check . # Run tests uv run pytest ``` ## License This project is available under the MIT License.