Open Stocks MCP

An MCP (Model Context Protocol) server providing access to stock market data and trading capabilities through multiple broker APIs.

Features

🚀 Current Status: v0.7.0-dev - Multi-Broker Support (Robinhood + Schwab)

✅ 104 MCP tools total - 80 Robinhood + 24 Schwab (4 deprecated)
✅ Multi-broker architecture - Support for Robinhood and Charles Schwab
✅ Complete trading functionality - stocks, options, order management
✅ Live trading validated - Robinhood stock and options trading tested with real orders
✅ Production-ready - HTTP transport, Docker support, comprehensive testing
✅ Schwab integration complete - OAuth authentication, 24 tools ready for testing
🔧 Account details fixed - Real financial data instead of N/A values

Installation

pip install open-stocks-mcp

For development:

git clone https://github.com/Open-Agent-Tools/open-stocks-mcp.git
cd open-stocks-mcp
uv pip install -e .

Quick Start

1. Set Up Credentials

Create a .env file:

For Robinhood:

ROBINHOOD_USERNAME=your_email@example.com
ROBINHOOD_PASSWORD=your_password

For Schwab (optional):

SCHWAB_API_KEY=your_api_key
SCHWAB_APP_SECRET=your_app_secret
SCHWAB_CALLBACK_URL=https://127.0.0.1:8182/
SCHWAB_TOKEN_PATH=~/.tokens/schwab_token.json

# Enable both brokers
ENABLED_BROKERS=robinhood,schwab

Note: Schwab requires a developer account and API approval (several days). See docs/SCHWAB_INTEGRATION_PLAN.md for details.

2. Start the Server

HTTP Transport (Recommended)

open-stocks-mcp-server --transport http --port 3001

STDIO Transport

open-stocks-mcp-server --transport stdio

3. Test the Server

# Health check (HTTP transport)
curl http://localhost:3001/health

# Interactive testing
uv run mcp dev src/open_stocks_mcp/server/app.py

Docker Deployment

Production Docker Setup:

cd examples/open-stocks-mcp-docker
docker-compose up -d

Features:

Persistent session storage
Automatic log rotation
Health monitoring
Security headers and CORS

MCP Client Integration

Claude Desktop

Add to your MCP settings (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "open-stocks": {
      "command": "open-stocks-mcp-server",
      "args": ["--transport", "stdio"]
    }
  }
}

HTTP Transport Integration

{
  "mcpServers": {
    "open-stocks": {
      "command": "python",
      "args": ["-m", "mcp_http_client", "http://localhost:3001/mcp"]
    }
  }
}

Available Tools

🏦 Multi-Broker Support

Robinhood Tools (80 tools):

All existing Robinhood functionality maintained
No breaking changes to existing API

Schwab Tools (24 tools):

Account & Portfolio (5 tools) - account numbers, balances, positions
Market Data (5 tools) - quotes, price history, instrument search
Trading (8 tools) - market/limit buy/sell, order management
Options (6 tools) - chains, expirations, positions, buy/sell

All Schwab tools use schwab_ prefix (e.g., schwab_get_portfolio, schwab_buy_stock_market).

Robinhood Tools by Category

Account & Portfolio (15 tools)

Account information and details
Portfolio positions and holdings
Day trading metrics and history
Stock and options order history

Market Data (12 tools)

Real-time stock quotes and fundamentals
Market movers and top performers
Sector analysis and market trends
Historical price data

Options Trading (15 tools)

Options chains and market data
Position aggregation and analysis
Historical options data
Options instrument search

Watchlists & Profiles (8 tools) ✅ Watchlist Management Tested

Watchlist management - All 5 tools working (add/remove symbols tested with AMC)
User profile and settings
Investment preferences
Account features

Market Research (10 tools)

Earnings data and analysis
Stock ratings and news
Dividend information
Corporate actions and splits

Analytics & Monitoring (5 tools)

Portfolio analytics
Performance metrics
Server health monitoring
Interest and loan payments

Notifications (12 tools)

Account notifications
Margin calls and interest
Subscription management
Referral tracking

Advanced Instruments (4 tools)

Multi-symbol instrument lookup
Enhanced search capabilities
Level II market data (Gold required)
Direct instrument access

Trading Capabilities (15 tools)

Stock Orders (✅ Live Tested):

✅ Market orders - Buy/sell tested with XOM and AMC
✅ Limit orders - Buy/sell tested with XOM ($106) and AMC ($3)
✅ Stop-loss orders - Sell tested with AMC (25 shares at $2.50)
Individual and bulk order cancellation
❌ Deprecated: Trailing stop orders, fractional shares (uncommon use cases)

Options Orders (✅ Live Tested):

✅ Options limit orders (buy/sell) - API bugs fixed
✅ Options discovery and contract search
✅ Credit and debit spread strategies - API bugs fixed, ready for testing
Live validation: F $9 put sell order placed successfully

Order Management:

Cancel individual or all orders (stock and options)
View open positions
Order status tracking

Authentication

The server handles Robinhood's authentication requirements:

Device Verification: Automatic handling of new device approval
Multi-Factor Authentication: Support for SMS and app-based MFA
Session Persistence: Cached authentication to reduce re-verification

Development

Testing

pytest                           # All tests
pytest -m "journey_account"      # Fast account tests (~1.8s)
pytest -m "journey_market_data"  # Market data tests (~3.8s) 
pytest -m "not slow and not exception_test"  # Recommended for development

# See CLAUDE.md for complete journey testing guide

Code Quality

ruff check . --fix              # Lint and fix
ruff format .                   # Format code
mypy .                          # Type check

Google ADK Evaluation

# Set environment variables
export GOOGLE_API_KEY="your-google-api-key"
export ROBINHOOD_USERNAME="email@example.com"
export ROBINHOOD_PASSWORD="password"

# Start Docker server
cd examples/open-stocks-mcp-docker && docker-compose up -d

# Run evaluation
MCP_HTTP_URL="http://localhost:3001/mcp" adk eval examples/google_adk_agent tests/evals/list_available_tools_test.json --config_file_path tests/evals/test_config.json

Project Scope

Completed in v0.7.0-dev:

✅ Multi-broker architecture - Abstract broker layer supporting multiple brokers
✅ Schwab integration - 24 tools across account, market data, trading, and options
✅ OAuth authentication - Schwab OAuth 2.0 flow with automatic token refresh
✅ Graceful degradation - Server starts even if broker authentication fails
✅ Backward compatibility - All Robinhood tools unchanged, no breaking changes

Completed in v0.6.4:

✅ Enhanced Options Tools - New open_option_positions_with_details() enriches positions with call/put type
✅ Stock trading API fixes - Market, limit, and stop-loss buy/sell functions now working correctly
✅ Live stock trading validation - XOM and AMC orders successfully placed (market, limit, stop-loss)
✅ Tool deprecation - Removed 4 uncommon trading functions (buy_stock_stop_loss, trailing stops, fractional shares)
✅ Options trading API fixes - buy_option_limit, sell_option_limit, and spread strategies now working
✅ Live options validation - F $9 put successfully traded
✅ Options discovery - find_options function working correctly
✅ Options spreads fixed - Credit and debit spread functions corrected (API signature, data structure, symbol extraction)
✅ Watchlist management complete - All 5 watchlist tools working with live testing
✅ Watchlist API fixes - Fixed response format changes and parameter binding issues
✅ All trading functions ready - Phase 7 complete, ready for Phase 8

Next Priority (Schwab Testing):

⏳ Schwab journey tests (blocked by API credentials)
⏳ Live Schwab trading validation
⏳ Multi-broker integration tests
⏳ Schwab-specific documentation

Out of Scope:

Crypto trading tools
Banking/ACH transfers
Account modifications
Deposit/withdrawal functionality

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT License - see LICENSE file for details.

Security

Important Security Notes:

Live trading capabilities - Real orders are placed with actual money
Never commit credentials to version control
Use proper file permissions for .env files
Trading validation complete - Both stock and options trading tested
Always verify trades before execution in production
Options trading note: Selling options (like puts) can result in assignment and stock ownership

For security concerns, please see our security policy.

Disclaimer: This software is for educational and development purposes. Trading stocks and options involves substantial risk. Always verify trades and understand the risks before executing any financial transactions.

Name		Name	Last commit message	Last commit date
Latest commit History 139 Commits
.github		.github
.vscode		.vscode
contributing		contributing
docs		docs
examples		examples
scripts		scripts
src/open_stocks_mcp		src/open_stocks_mcp
temp		temp
tests		tests
.coverage		.coverage
.editorconfig		.editorconfig
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.python-version		.python-version
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
QA_REPORT_2025-10-06.md		QA_REPORT_2025-10-06.md
README.md		README.md
SCHWAB_STATUS.md		SCHWAB_STATUS.md
SECURITY.md		SECURITY.md
TODO.md		TODO.md
coverage.json		coverage.json
pyproject.toml		pyproject.toml
uv.lock		uv.lock

License

Open-Agent-Tools/open-stocks-mcp

Folders and files

Latest commit

History

Repository files navigation

Open Stocks MCP

Features

Installation

Quick Start

1. Set Up Credentials

2. Start the Server

3. Test the Server

Docker Deployment

MCP Client Integration

Claude Desktop

HTTP Transport Integration

Available Tools

🏦 Multi-Broker Support

Robinhood Tools by Category

Account & Portfolio (15 tools)

Market Data (12 tools)

Options Trading (15 tools)

Watchlists & Profiles (8 tools) ✅ Watchlist Management Tested

Market Research (10 tools)

Analytics & Monitoring (5 tools)

Notifications (12 tools)

Advanced Instruments (4 tools)

Trading Capabilities (15 tools)

Authentication

Development

Testing

Code Quality

Google ADK Evaluation

Project Scope

Contributing

License

Security

About

Topics

Resources

License

Code of conduct

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 29

Packages 0

Contributors 3

Uh oh!

Languages

Packages