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.6.5 - Multi-Broker Support (Robinhood + Schwab)

• ✅ MCP tools across Robinhood + Schwab (see Tool Reference for current breakdown)
• ✅ 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, tools ready for testing (see Tool Reference)
• 🔧 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 sync   # installs all deps including dev group

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 Schwab Setup Guide for full setup instructions.

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

# Prometheus metrics (no auth required)
curl http://localhost:3001/metrics

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

The /metrics endpoint exposes:

• open_stocks_mcp_tool_calls_total (counter by tool)
• open_stocks_mcp_tool_avg_calls_per_minute (gauge by tool; average over the rolling window)
• open_stocks_mcp_tool_latency_ms (gauge by tool and quantile: 0.50, 0.95, 0.99)

Distributed tracing setup (OpenTelemetry, Jaeger, Tempo):

• docs/OPENTELEMETRY_TRACING.md

MCP Tool Execution Timeout

Each MCP tools/call invocation is bounded by a configurable deadline. Tools that exceed the deadline return a structured JSON error instead of blocking the server indefinitely.

• YAML key: timeout.tool_execution_timeout_seconds (default: 30)
• Environment override: OPEN_STOCKS_MCP_TOOL_EXECUTION_TIMEOUT_SECONDS (e.g., 60)

When a tool times out its response body is:

{
  "status": "error",
  "error_type": "ToolExecutionTimeout",
  "failure_class": "timeout",
  "tool": "<tool_name>",
  "timeout_seconds": 30,
  "error": "Tool '...' exceeded the 30s execution limit"
}

The MCP result has isError: true; HTTP /mcp returns status 200 (not 500) so the client can inspect the structured error. Broker-level request timeouts (Robinhood 16 s, Schwab 30 s) remain in effect independently and count toward this deadline.

Operational Circuit Breaker Defaults

Broker call protection is enabled by default and reports state in MCP health_check, MCP rate_limit_status, HTTP /health, and HTTP /status.

• OPEN_STOCKS_MCP_CIRCUIT_BREAKER_ENABLED (default: true)
• OPEN_STOCKS_MCP_CIRCUIT_BREAKER_FAILURE_THRESHOLD (default: 5)
• OPEN_STOCKS_MCP_CIRCUIT_BREAKER_COOLDOWN_SECONDS (default: 60)

State meanings:

• closed: requests flow normally.
• open: broker calls fail fast until cooldown expires.
• half_open: one probe call is allowed; success resets to closed, failure returns to open.

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

Kubernetes / Orchestrated Deployment: See examples/kubernetes/README.md for Kustomize manifests covering HTTP transport, non-root security context, PVC-backed token/log persistence, and health probes.

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

Reference docs and runnable examples:

• API docs and notebook guide, including the generated tool reference

🏦 Multi-Broker Support

Robinhood Tools:

• All existing Robinhood functionality maintained
• No breaking changes to existing API

Schwab Tools:

• Account & Portfolio - account numbers, balances, positions, day trades
• Market Data - quotes, price history, instrument search, market hours, movers
• Trading - market/limit buy/sell, order management, transactions
• Options - chains, expirations, positions, buy/sell, spreads, cancellation
• Streaming - real-time account activity, options quotes, and level2 snapshot
• Dividends/Income - dividends, dividends by symbol, interest payments, stock loan payments

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

---

Robinhood Tools by Category

Account & Portfolio

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

Market Data

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

Options Trading

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

Watchlists & Profiles ✅ 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

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

Analytics & Monitoring

• Portfolio analytics
• Performance metrics
• Server health monitoring
• Interest and loan payments

Notifications

• Account notifications
• Margin calls and interest
• Subscription management
• Referral tracking

Advanced Instruments

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

Trading Capabilities

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:

• App-Push Approval: Automatic handling of app-based device approval (approve via Robinhood mobile app).
• SMS/Email MFA Code: Set ROBINHOOD_MFA_CODE before login attempts to complete code-based verification (time-sensitive, typically 5-10 minutes).
• Session Persistence: Cached and encrypted authentication to reduce re-verification.

Development

Testing

uv run pytest                           # All tests (works after uv sync)
uv run pytest -m "journey_account"      # Fast account tests (~1.8s)
uv run pytest -m "journey_market_data"  # Market data tests (~3.8s)
uv run pytest -m "not slow and not exception_test"  # Recommended for development
uv run pytest -m rate_limited           # Opt-in live API tests that may hit broker rate limits
RUN_RATE_LIMITED=1 uv run pytest        # Include rate-limited tests in a full run
uv run pytest -m performance tests/performance -v  # Mocked, CI-safe benchmarks
RUN_PERFORMANCE=1 uv run pytest         # Include performance tests in a full run

# See CLAUDE.md for complete journey testing guide

Code Quality

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

YAML Configuration

Open Stocks MCP can load configuration from open-stocks-mcp.yaml or config.yaml in the current working directory. You can also set an explicit path with OPEN_STOCKS_CONFIG=/path/to/config.yaml or OPEN_STOCKS_CONFIG_FILE=/path/to/config.yaml (OPEN_STOCKS_MCP_CONFIG remains supported for backward compatibility).

Environment variables always win over YAML values, including:

• MCP_SERVER_NAME, LOG_LEVEL
• RATE_LIMIT_CALLS_PER_MINUTE, RATE_LIMIT_CALLS_PER_HOUR, RATE_LIMIT_BURST_SIZE
• CACHE_TTL_MARKET_SECONDS, CACHE_TTL_ACCOUNT_SECONDS, CACHE_MAX_SIZE
• ENABLE_CACHE
• OPEN_STOCKS_MCP_BATCH_SIZE, OPEN_STOCKS_MCP_QUEUE_MAX_WAIT

Feature flags support safe defaults plus per-environment overrides:

environment: production
feature_flags:
  brokers.robinhood:
    default: true
  brokers.schwab:
    default: false
    environments:
      production: true

Unknown feature flags resolve to disabled (false).

See config.yaml.example for the supported schema.

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/0_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 - tools across account, market data, trading, options, streaming, and dividends/income (see Tool Reference)
• ✅ 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

• CONTRIBUTING.md — development setup, workflow, and code guidelines
• contributing/README.md — local debugging and editor configuration

License

Apache License 2.0 - 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.