Schwab Model Context Protocol Server

This is a server that implements the Model Context Protocol (MCP) for the Schwab API using schwab-py and the MCP 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 gated behind Discord approvals (bypass with --jesus-take-the-wheel)
• Designed to integrate with Large Language Models (LLMs)

Installation

# 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:

# 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:

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:

# 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 \
  --discord-token YOUR_DISCORD_BOT_TOKEN \
  --discord-channel-id YOUR_APPROVAL_CHANNEL_ID \
  --discord-approver DISCORD_USER_ID [--discord-approver ANOTHER_USER_ID ...]

# 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 \
  --discord-token YOUR_DISCORD_BOT_TOKEN \
  --discord-channel-id YOUR_APPROVAL_CHANNEL_ID

# Run with account modification tools auto-approved (no Discord prompt)
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.

Discord-related flags can also be provided via environment variables:

• SCHWAB_MCP_DISCORD_TOKEN
• SCHWAB_MCP_DISCORD_CHANNEL_ID
• SCHWAB_MCP_DISCORD_TIMEOUT (optional, defaults to 600 seconds)
• SCHWAB_MCP_DISCORD_APPROVERS (optional comma-separated list of Discord user IDs)

Container Image

Published container images are available at ghcr.io/jkoelker/schwab-mcp. The image runs schwab-mcp server by default and persists token data under /root/.local/share/schwab-mcp unless overridden.

podman run --rm --interactive \
  --env SCHWAB_CLIENT_ID \
  --env SCHWAB_CLIENT_SECRET \
  --env SCHWAB_CALLBACK_URL \
  --env SCHWAB_MCP_DISCORD_TOKEN \
  --env SCHWAB_MCP_DISCORD_CHANNEL_ID \
  --publish 8182:8182 \
  --volume ~/.local/share/schwab-mcp:/schwab-mcp \
  ghcr.io/jkoelker/schwab-mcp:latest \
    server \
    --token-path /schwab-mcp/token.yaml

The container entrypoint reads the same environment variables as the CLI, so you can override or add flags by appending them (for example, ... ghcr.io/jkoelker/schwab-mcp:latest --jesus-take-the-wheel). To explore other entry points, run docker run ghcr.io/jkoelker/schwab-mcp:latest --help.

Discord approval setup

1. Create or open your application at https://discord.com/developers/applications, add a Bot, reset the token, and paste it into SCHWAB_MCP_DISCORD_TOKEN.
2. In the Installation tab (left sidebar) set Install Link to None so the default authorization link is disabled.
3. Open the Bot tab, toggle Public Bot off.
4. Use OAuth2 → URL Generator to build the invite link by selecting the bot scope. When the permissions matrix appears, grant the bot:
   • View Channel
   • Send Messages
   • Embed Links
   • Add Reactions
   • Read Message History
   • Manage Messages
5. Copy the generated URL (the permissions integer reflects the boxes you checked), open it while logged into the Discord account that owns the approval server, and authorize the bot into the channel where approvals should post.

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 27-39 will pause for Discord approval before executing. Pass --jesus-take-the-wheel to bypass the approval workflow entirely.

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

1. get_account_numbers - Get mapping of account IDs to account hashes
2. get_accounts - Get information for all linked Schwab accounts
3. get_accounts_with_positions - Get accounts with position information
4. get_account - Get information for a specific account
5. get_account_with_positions - Get specific account with position information
6. get_user_preferences - Get user preferences for all accounts including nicknames

Orders

1. get_order - Get details for a specific order
2. get_orders - Get orders for a specific account

Quotes

1. get_quotes - Get quotes for specified symbols

Price History

1. get_advanced_price_history - Get advanced price history for a specific symbol
2. get_price_history_every_minute - Get price history with minute frequency
3. get_price_history_every_five_minutes - Get price history with five minute frequency
4. get_price_history_every_ten_minutes - Get price history with ten minute frequency
5. get_price_history_every_fifteen_minutes - Get price history with fifteen minute frequency
6. get_price_history_every_thirty_minutes - Get price history with thirty minute frequency
7. get_price_history_every_day - Get price history with daily frequency
8. get_price_history_every_week - Get price history with weekly frequency

Options

1. get_option_chain - Get option chain for a specific symbol
2. get_advanced_option_chain - Get advanced option chain for a specific symbol
3. get_option_expiration_chain - Get option expiration information for a symbol

Transactions

1. get_transactions - Get transactions for a specific account
2. get_transaction - Get details for a specific transaction

Account Modification Tools (Requires --jesus-take-the-wheel flag)

1. cancel_order - Cancel a specific order

Equity Orders

1. place_equity_market_order - Place a market order for a stock or ETF
2. place_equity_limit_order - Place a limit order for a stock or ETF
3. place_equity_stop_order - Place a stop order for a stock or ETF
4. place_equity_stop_limit_order - Place a stop-limit order for a stock or ETF
5. place_equity_order - Unified function for placing any equity order type

Option Orders

1. create_option_symbol - Create a properly formatted option symbol from components
2. place_option_market_order - Place a market order for an option contract
3. place_option_limit_order - Place a limit order for an option contract
4. place_option_order - Unified function for placing any option order type

Complex Order Strategies

1. place_one_cancels_other_order - Create an OCO order pair where execution of one cancels the other
2. place_first_triggers_second_order - Create a sequence where one order triggers another upon execution
3. 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

# 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.