Metadata-Version: 2.4
Name: mseep-schwab-mcp
Version: 0.1.1
Summary: Schwab Model Context Protocol (MCP) for the Schwab API
Home-page: 
Author: mseep
Author-email: mseep <support@skydeck.ai>
Maintainer-email: mseep <support@skydeck.ai>
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anyio>=4.9.0
Requires-Dist: click>=8.1.8
Requires-Dist: mcp>=1.4.1
Requires-Dist: platformdirs>=4.3.7
Requires-Dist: pyyaml>=6.0.2
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

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

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

## Security Warning

The `--jesus-take-the-wheel` flag enables LLMs to perform actions that can modify your account state, including:
- Canceling orders
- Other actions that may have financial implications (more tools to be added in future releases)

Only use this flag in controlled environments and understand the risks involved.

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