# Schwab MCP Server
A read-only Model Context Protocol (MCP) server for Charles Schwab API. Access your Schwab account data and market information through AI assistants like Claude, ChatGPT, and more.
## Features
- **Portfolio Analysis** - View positions with cost basis, quantity, and market value
- **Real-time Quotes** - Get current prices for stocks and ETFs
- **Options Data** - Access options chains with Greeks
- **Price History** - Historical OHLCV data for technical analysis
- **Account Info** - View account balances and details
**Security Note:** This server is strictly READ-ONLY. No trading or account modification functionality is implemented.
## Prerequisites
- Python 3.10 or higher
- A Charles Schwab Developer account with:
- App Key (Client ID)
- App Secret (Client Secret)
- A valid Refresh Token
- Callback URL configured
## Installation
1. Clone the repository:
```bash
git clone https://github.com/yourusername/schwab-mcp-server.git
cd schwab-mcp-server
```
2. Create and activate a virtual environment:
```bash
python -m venv venv
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate
```
3. Install the package:
```bash
pip install -e .
```
## Configuration
### Environment Variables
Create a `.env` file in the project root:
```bash
SCHWAB_CALLBACK_URL=https://127.0.0.1:8182/callback
SCHWAB_TOKEN_PATH=~/.schwab-mcp/token.json
LOG_LEVEL=INFO
# Optional overrides if you don't keep them in the token file:
# SCHWAB_CLIENT_ID=your_app_key_here
# SCHWAB_CLIENT_SECRET=your_app_secret_here
```
### Initial Token Setup
Create the token file at the path specified in `SCHWAB_TOKEN_PATH` (default: `~/.schwab-mcp/token.json`):
```json
{
"client_id": "your_app_key_here",
"client_secret": "your_app_secret_here",
"access_token": "",
"refresh_token": "YOUR_REFRESH_TOKEN_HERE",
"expires_at": 0,
"token_type": "Bearer"
}
```
Setting `expires_at` to `0` forces an automatic token refresh on first use.
The MCP server will load `client_id` and `client_secret` directly from this token file. Environment variables with the same names can override these values if needed.
---
## Client Setup
### Claude Desktop
#### Windows (Automated)
Run the PowerShell script to automatically configure Claude Desktop:
```powershell
.\scripts\update_claude_schwab.ps1
```
The script will:
1. Stop Claude Desktop (prompts for confirmation)
2. Clear MCP-related cache files
3. Update the config with correct paths to the venv Python and src directory
4. Restart Claude Desktop
**Options:**
- `-RepoPath` - Path to this repo (default: auto-detected)
- `-SkipRestart` - Update config without restarting Claude
- `-ServerName` - MCP server name in config (default: `schwab`)
#### Manual Configuration
**macOS:** Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** Edit `%APPDATA%\Claude\claude_desktop_config.json`
Add the following configuration:
```json
{
"mcpServers": {
"schwab": {
"command": "python",
"args": ["-m", "schwab_mcp.server"],
"cwd": "/path/to/schwab-mcp-server",
"env": {
"SCHWAB_CALLBACK_URL": "https://127.0.0.1:8182/callback",
"SCHWAB_TOKEN_PATH": "/path/to/.schwab-mcp/token.json",
"PYTHONPATH": "/path/to/schwab-mcp-server/src",
"LOG_LEVEL": "INFO"
}
}
}
}
```
Restart Claude Desktop after saving the configuration.
---
### ChatGPT Desktop
ChatGPT Desktop supports MCP servers through its settings. To configure:
1. Open ChatGPT Desktop
2. Go to **Settings** > **Features** > **MCP Servers**
3. Click **Add Server** and enter:
- **Name:** `schwab`
- **Command:** `python`
- **Arguments:** `-m schwab_mcp.server`
- **Working Directory:** `/path/to/schwab-mcp-server`
4. Add environment variables (client id/secret are read from the token file):
- `SCHWAB_CALLBACK_URL`: https://127.0.0.1:8182/callback
- `SCHWAB_TOKEN_PATH`: /path/to/.schwab-mcp/token.json
5. Save and restart ChatGPT Desktop
File-based setup (auto-detected by ChatGPT Desktop):
- macOS: create `~/Library/Application Support/ChatGPT/.well-known/mcp.json`
- Windows: create `%APPDATA%\ChatGPT\.well-known\mcp.json`
Copy `chatgpt_desktop_config.example.json` to that location and update the paths to match your environment (Python executable, repo path, and token path). Restart ChatGPT Desktop after saving.
---
### Claude Code (CLI)
Add the MCP server to your Claude Code configuration. Create or edit `~/.claude/claude_code_config.json`:
```json
{
"mcpServers": {
"schwab": {
"command": "python",
"args": ["-m", "schwab_mcp.server"],
"cwd": "/path/to/schwab-mcp-server",
"env": {
"SCHWAB_CALLBACK_URL": "https://127.0.0.1:8182/callback",
"SCHWAB_TOKEN_PATH": "/path/to/.schwab-mcp/token.json"
}
}
}
}
```
Alternatively, you can add it to your project's `.claude/settings.json` for project-specific configuration:
```json
{
"mcpServers": {
"schwab": {
"command": "python",
"args": ["-m", "schwab_mcp.server"],
"cwd": "/path/to/schwab-mcp-server",
"env": {
"SCHWAB_CALLBACK_URL": "https://127.0.0.1:8182/callback",
"SCHWAB_TOKEN_PATH": "/path/to/.schwab-mcp/token.json"
}
}
}
}
```
---
### OpenAI Codex
For Codex CLI, configure the MCP server in your environment:
1. Set up environment variables in your shell profile (`.bashrc`, `.zshrc`, etc.):
```bash
export SCHWAB_CALLBACK_URL="https://127.0.0.1:8182/callback"
export SCHWAB_TOKEN_PATH="$HOME/.schwab-mcp/token.json"
# Optional overrides if you don't keep them in the token file:
# export SCHWAB_CLIENT_ID="your_client_id"
# export SCHWAB_CLIENT_SECRET="your_client_secret"
```
2. Configure Codex to use the MCP server by adding to your Codex configuration:
```json
{
"mcpServers": {
"schwab": {
"command": "python",
"args": ["-m", "schwab_mcp.server"],
"cwd": "/path/to/schwab-mcp-server"
}
}
}
```
---
## Available Tools
| Tool | Description |
|------|-------------|
| `get_account` | Get account information including type and balances |
| `get_positions` | Get all positions with cost basis and market value |
| `get_quote` | Get real-time quote for a single symbol |
| `get_quotes` | Get real-time quotes for multiple symbols |
| `get_option_chain` | Get options chain with Greeks for a symbol |
| `get_price_history` | Get historical OHLCV price data |
## Usage Examples
Once configured, you can ask your AI assistant questions like:
- "What are my current positions and their cost basis?"
- "Get me a quote for AAPL"
- "Show me the options chain for MSFT expiring in January"
- "What's the price history for NVDA over the last 6 months?"
- "What are my account balances?"
## Testing
### Using MCP Inspector
Test the server locally using the MCP Inspector:
```bash
npx @modelcontextprotocol/inspector python -m schwab_mcp.server
```
### Manual Test
Verify authentication is working:
```bash
python -c "from schwab_mcp.auth import TokenManager; from schwab_mcp.config import settings; tm = TokenManager(settings.schwab_client_id, settings.schwab_client_secret, settings.schwab_token_path); tm.load_token(); print('Token loaded successfully')"
```
## Troubleshooting
### Token Refresh Fails
- Ensure your refresh token is valid and not expired (7-day expiration)
- Verify your client ID and secret are correct
- Check that your Schwab Developer app is approved and active
### Server Won't Start
- Verify Python 3.10+ is installed: `python --version`
- Ensure all dependencies are installed: `pip install -e .`
- Check that the `.env` file exists and has correct values
### No Data Returned
- Confirm your Schwab account has the appropriate permissions
- Check if markets are open (some data limited outside trading hours)
- Review logs for API error messages
## Security
- **Read-only access only** - No trading or account modification capabilities
- **Token storage** - Tokens are stored locally with restricted file permissions (600)
- **No credential logging** - Sensitive data is never written to logs
- **Environment variables** - Credentials should be passed via environment, not hardcoded
## References
- [Schwab Developer Portal](https://developer.schwab.com/)
- [MCP Specification](https://spec.modelcontextprotocol.io/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
## License
MIT - Use at your own risk. Not affiliated with Charles Schwab.
