schwab-mcp
README.md
# schwab-mcp
A **local MCP server (stdio)** for accessing [Charles Schwab](https://www.schwab.com)
account information from an AI client: positions, transaction history, and
option chains. Everything runs on your machine: no incoming sockets, and
credentials that never leave your computer.
## Disclaimer
This is an independent, **unofficial** project. It is not affiliated with,
endorsed by, or sponsored by Charles Schwab & Co., Inc. "Schwab" and related
marks belong to their respective owners.
- **Read-only by design**: the exposed tools only read positions,
transaction history, and option chains — no order placement or any other
write operation.
- You are responsible for complying with the Schwab developer program terms
and API policies that govern your own application keys.
- No warranty: the software is provided "as is" (see [LICENSE](LICENSE)).
Nothing here is financial, investment, tax, or legal advice.
## Documentation
| Topic | Where |
|-------|-------|
| Installation and setup | [docs/installation.md](docs/installation.md) |
| Usage, authorization, and troubleshooting | [docs/usage.md](docs/usage.md) |
| Tools reference for AI agents | [docs/tools.md](docs/tools.md) |
| Development guide (setup and workflow) | [docs/development.md](docs/development.md) |
| Change history | [docs/CHANGELOG.md](docs/CHANGELOG.md) |
## Tools
The MCP server (`schwab-mcp serve`) exposes **six read-only tools**:
| Tool | What it does |
|------|--------------|
| `get_open_positions` | All effective holdings of every linked account in a single call. |
| `get_transaction_history` | Movements of all linked accounts in a date range, with an optional instrument filter and pagination. |
| `get_option_chain` | Full option chain of an underlying in one call, with strike, delta, and DTE filters, including the Greeks. |
| `get_quotes` | Current quotes for 1..20 symbols (equities, ETFs, indexes, option contracts) in one call: last, bid/ask, volume, net change, freshness, last-trade time. |
| `get_price_history` | OHLCV candles for one symbol at 5m/15m/30m/1h/daily/weekly with named period presets (default: daily, 1 month; at most 260 candles per call), extended-hours opt-in for intraday, and an in-progress marker on the forming candle. |
| `get_option_expiration_chain` | The upcoming option expirations of one underlying in one cheap call: expiration date, DTE (calendar days), and settlement type — no strikes, quotes, or Greeks; DTE-ceiling semantics shared with `get_option_chain`. |
Every tool returns a structured JSON result with an explicit `outcome`
(`ok`, `transient_failure`, `reauth_required`, …), so an agent can act
without human intervention.
The tool set is intentionally small and basic — but it is fast,
token-efficient, and composable: from just positions, history, quotes,
and option chains, an agent can run surprisingly sophisticated analyses
(portfolio performance, trade-chain reconstruction, options-strategy
sizing, dividend tracking, and more). We are open to suggestions for
new tools — [open an issue](https://github.com/lautarobonetto/schwab-mcp/issues)
or reach out and tell us what you would like to see next.
### What you can do
- **Positions**: see everything you hold across all linked accounts
(optionally with the full provider passthrough via `extended: true`).
- **Transaction history**: reconstruct what happened in an account —
trades, transfers, dividends — filtered by symbol (equities, ETFs,
option underlyings, or full OCC symbols), paginated at 50 movements
per page. Maximum window per query: **1 year**.
- **Quotes**: mark any position to market with one small call — current
price, bid/ask, volume, net change, and an explicit freshness state
(`realtime` / `delayed` / `closed`) so the agent knows how stale a
price is without a second call.
- **Option chains**: browse strikes around the money or target a
delta (e.g. `delta_target: 0.2` for short-strangle legs), bounded by
DTE, with bid/ask, volume, open interest, IV, and the 5 Greeks.
- All of it **read-only, local, and secret-free**: credentials never
appear in outputs, and no operation places orders or moves money.
### What you cannot do
- **No write operations**: no order placement, modification, or
cancellation — the tools only read positions, history, quotes, chains,
and candles.
- **No streaming market data and no fundamentals**: quotes are
point-in-time snapshots, not streaming feeds; there are no
fundamentals, earnings calendars, or dividend dates (an external FMP
MCP covers those).
either. For those needs (earnings
dates, ex-dividends, financial statements, ratios) we recommend
complementing this MCP with the [FMP](https://site.financialmodelingprep.com/)
MCP, which covers Schwab's gaps on that front.
- **No account management**: no balances snapshot, bank links, or
preferences; account identifiers are opaque hashes.
- **Hard limits**: transaction windows longer than 1 year must be
split into consecutive queries; option chains never return
expirations beyond a 60-day DTE ceiling (there is a `dte_max`, but
no `dte_min`).
The exact input/output schema of every tool — field by field, with
error semantics and agent playbooks — lives in
[docs/tools.md](docs/tools.md).
### Examples
Positions of all linked accounts:
```json
{"name": "get_open_positions", "arguments": {}}
```
AAPL movements over three months:
```json
{"name": "get_transaction_history", "arguments": {
"start_date": "2026-07-01", "end_date": "2026-09-30", "symbol": "AAPL"}}
```
Puts around a −0.20 delta (≤ 5 strikes per expiration, small payload):
```json
{"name": "get_option_chain", "arguments": {
"symbol": "SPY", "option_type": "puts", "delta_target": 0.2}}
```
Current quotes for a whole portfolio in one call:
```json
{"name": "get_quotes", "arguments": {
"symbols": ["AAPL", "NOK", "$SPX", "AAPL 261127C350"]}}
```
## Commands
```sh
uv sync # set up the environment
uv run pytest # full test suite
uv run schwab-mcp auth # interactive authorization
uv run schwab-mcp serve # MCP server over stdio
uv run schwab-mcp auth-status # local credential diagnostics
uv run schwab-mcp renew # explicit renewal
```
## Credential safety
Schwab credentials and tokens live only in
`~/.schwab-mcp/tokens.db` (configurable), never in logs, outputs, or
the repository. The project constitution governs all changes:
[.specify/memory/constitution.md](.specify/memory/constitution.md);
the project direction and planned future tools live in the spec
roadmap: [.specify/memory/roadmap.md](.specify/memory/roadmap.md).
The MCP is read-only by design: no spec places orders or moves money.
## Contributing
Want to develop on this project? Read the
[development guide](docs/development.md): what to install (uv, OpenCode,
codebase-memory-mcp, Spec Kit), and the spec-driven, test-first
workflow every change must follow. Suggestions for new tools are
welcome — [open an issue](https://github.com/lautarobonetto/schwab-mcp/issues).
## License
[MIT](LICENSE)This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues