How do I use thetadata-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@thetadata-mcp Get the current OHLC data for AAPL" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

thetadata-mcp

by drmartell

Overview Schema Source Related Servers Discussions Admin

Python

Local

Theta Data MCP Server

A local MCP (Model Context Protocol) wrapper for the Theta Data API, providing AI models with access to real-time and historic stock, options, and index data.

Overview

This MCP server is generated from the Theta Data OpenAPI specification using FastMCP. It exposes API endpoints as MCP tools, allowing AI assistants to query market data directly.

Supported Data Types

Stocks: Symbols, EOD data, OHLC, trades, quotes, snapshots
Options: Symbols, expirations, strikes, contracts, Greeks, implied volatility
Indices: Symbols, prices, OHLC, market values
Calendar: Market open dates

Related MCP server: siftingio-mcp

Prerequisites

Python 3.10+
uv for package management
Theta Data terminal running locally (default: http://127.0.0.1:25503)
A Theta Data subscription (subscribe here)

Installation

# Create virtual environment and install all dependencies (including dev)
uv sync

Usage

Running the Server

# Run with stdio transport (default)
uv run server.py

# Run with SSE transport
uv run server.py --transport sse

# Custom base URL
uv run server.py --base-url http://localhost:25503/v3

# Custom timeout
uv run server.py --timeout 60.0

Environment Variables

Variable	Description	Default
`THETADATA_BASE_URL`	Theta Data API base URL	`http://127.0.0.1:25503/v3`
`THETADATA_TIMEOUT`	Request timeout in seconds	`30.0`

MCP Client Configuration

Add the following to your MCP client config, replacing /path/to/thetadata-mcp with the actual path to this repository:

{
  "mcpServers": {
    "thetadata": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/thetadata-mcp",
        "run",
        "server.py"
      ],
      "env": {
        "THETADATA_BASE_URL": "http://127.0.0.1:25503/v3",
        "THETADATA_TIMEOUT": "30.0"
      }
    }
  }
}

Available Tools

The server exposes all Theta Data v3 API endpoints as MCP tools, including:

Stock Data

stock_list_symbols - List all stock symbols
stock_list_dates - List available dates for a request type
stock_snapshot_ohlc - Real-time OHLC data
stock_snapshot_trade - Real-time trade data
stock_snapshot_quote - Real-time quote data
stock_history_eod - Historic EOD data
stock_history_ohlc - Historic OHLC bars
stock_history_trade - Historic trade data
stock_history_quote - Historic quote data

Options Data

option_list_symbols - List optionable symbols
option_list_expirations - List expirations for a symbol
option_list_strikes - List strikes for an expiration
option_list_contracts - List option contracts
option_snapshot_ohlc - Real-time option OHLC
option_snapshot_greeks_all - All Greeks (delta, gamma, theta, vega, rho)
option_snapshot_greeks_implied_volatility - Implied volatility
option_history_eod - Historic option EOD data
option_history_greeks_all - Historic Greeks data

Index Data

index_list_symbols - List index symbols
index_snapshot_price - Real-time index prices
index_history_eod - Historic index EOD data

Calendar

calendar_open_today - Check if market is open today
calendar_on_date - Check if market is open on a specific date

See the Theta Data API documentation for full details on parameters and responses.

Example Queries

Once connected to an MCP client, you can ask:

"List all available stock symbols"
"Get the current OHLC data for AAPL"
"What are the available option expirations for SPY?"
"Show me the Greeks for the SPY 500 call expiring next Friday"
"Is the market open today?"

Development

Pre-commit Hooks

This project uses pre-commit to run ruff linting and formatting automatically on every commit.

Setup (one-time per clone):

uv run pre-commit install

The hook will now automatically check and fix code formatting when you commit changes.

Manual Development Commands

# Run linting with uv
uv run ruff check .

# Format code with uv
uv run ruff format .

# Regenerate endpoints_by_subscription documentation
uv run python generate_endpoint_docs.py

Regenerating Endpoint Documentation

The generate_endpoint_docs.py script reads the x-min-subscription field from openapiv3_updated.yaml and regenerates the markdown files in endpoints_by_subscription/. Each tier file shows all endpoints available at that subscription level and below (cumulative):

endpoints_free.md - Free tier endpoints
endpoints_value.md - Free + Value tier endpoints
endpoints_standard.md - Free + Value + Standard tier endpoints
endpoints_professional.md - All endpoints

License

MIT License - See LICENSE file for details.

Resources

Available Tools

59 tools

calendar_on_dateC

[VALUE] Equity market schedule for a given date.

Inputs: date (required).

calendar_open_todayB

[FREE] Current day equity market schedule.

Inputs: no named parameters.

calendar_yearC

[VALUE] Equity market holidays for a given year.

Inputs: year (required).

index_at_time_priceC

[VALUE] Index price at a specific time of day.

Inputs: symbol (required), time_of_day (required), end_date, start_date.

index_history_eodB

[FREE] End-of-day report for an index. Generated at 17:15 ET daily.

Inputs: symbol (required), end_date, start_date.

index_history_ohlcC

[STANDARD] Historical OHLC bars for an index.

Inputs: symbol (required), interval (required), end_date, end_time, +2 more.

index_history_priceC

[VALUE] Historical price reports for an index. Max 1 month per request.

Inputs: symbol (required), interval (required), date, end_date, +3 more.

index_list_datesC

[FREE] List available data dates for an index by request type and symbol.

Inputs: symbol (required).

index_list_symbolsA

[FREE] List all index symbols. Updated overnight.

Inputs: no named parameters.

index_snapshot_market_valueC

[STANDARD] Real-time market value for an index.

Inputs: symbol (required), min_time.

index_snapshot_ohlcB

[STANDARD] Real-time current-day OHLC for an index.

Inputs: symbol (required), min_time.

index_snapshot_priceB

[STANDARD] Real-time last price for an index.

Inputs: symbol (required), min_time.

option_at_time_quoteC

[VALUE] Last option NBBO quote at a specific time of day.

Inputs: symbol (required), expiration (required), time_of_day (required), right, +5 more.

option_at_time_tradeC

[STANDARD] Last option trade at a specific time of day.

Inputs: symbol (required), expiration (required), time_of_day (required), right, +5 more.

option_history_eodC

[FREE] End-of-day report for options. Generated at 17:15 ET daily.

Inputs: symbol (required), expiration (required), right, strike, +4 more.

option_history_greeks_allC

[PROFESSIONAL] Historical greeks (all orders) from midpoint prices. Max 1 month per request.

Inputs: symbol (required), interval (required), expiration (required), date, +11 more.

option_history_greeks_eodB

[STANDARD] EOD greeks for all contracts by symbol and expiration. Use expiration=* for all.

Inputs: symbol (required), expiration (required), right, strike, +9 more.

option_history_greeks_first_orderB

[STANDARD] Historical first-order greeks from midpoint prices. Max 1 month per request.

Inputs: symbol (required), interval (required), expiration (required), date, +11 more.

option_history_greeks_implied_volatilityC

[STANDARD] Historical IV from bid, mid, and ask prices. Max 1 month per request.

Inputs: symbol (required), interval (required), expiration (required), date, +11 more.

option_history_greeks_second_orderA

[PROFESSIONAL] Historical second-order greeks from midpoint prices. Max 1 month per request.

Inputs: symbol (required), interval (required), expiration (required), date, +11 more.

option_history_greeks_third_orderB

[PROFESSIONAL] Historical third-order greeks from midpoint prices. Max 1 month per request.

Inputs: symbol (required), interval (required), expiration (required), date, +11 more.

option_history_ohlcA

[VALUE] Historical OHLC bars for options. Max 1 month per request.

Inputs: symbol (required), interval (required), expiration (required), date, +7 more.

option_history_open_interestA

[VALUE] Historical open interest for options. Reported ~06:30 ET, reflects prior day.

Inputs: symbol (required), expiration (required), date, right, +5 more.

option_history_quoteC

[VALUE] NBBO quote history for options. Supports interval aggregation. Max 1 month, requires expiration.

Inputs: symbol (required), interval (required), expiration (required), date, +8 more.

option_history_tradeB

[STANDARD] Tick-level trade history for options. Max 1 month, requires expiration.

Inputs: symbol (required), expiration (required), date, right, +7 more.

option_history_trade_greeks_allB

[PROFESSIONAL] Greeks calculated at each trade. Max 1 month, requires expiration.

Inputs: symbol (required), expiration (required), date, right, +11 more.

option_history_trade_greeks_first_orderB

[PROFESSIONAL] First-order greeks at each trade. Max 1 month, requires expiration.

Inputs: symbol (required), expiration (required), date, right, +11 more.

option_history_trade_greeks_implied_volatilityC

[PROFESSIONAL] IV calculated at each trade. Max 1 month, requires expiration.

Inputs: symbol (required), expiration (required), date, right, +11 more.

option_history_trade_greeks_second_orderB

[PROFESSIONAL] Second-order greeks at each trade. Max 1 month, requires expiration.

Inputs: symbol (required), expiration (required), date, right, +11 more.

option_history_trade_greeks_third_orderA

[PROFESSIONAL] Third-order greeks at each trade. Max 1 month, requires expiration.

Inputs: symbol (required), expiration (required), date, right, +11 more.

option_history_trade_quoteA

[STANDARD] Trade history paired with contemporaneous NBBO quotes for options. Max 1 month, requires expiration.

Inputs: symbol (required), expiration (required), date, right, +8 more.

option_list_contractsA

[VALUE] List contracts traded or quoted on a date. Supports symbol filtering. Real-time.

Inputs: date (required), request_type (required), symbol, max_dte.

option_list_datesA

[FREE] List available data dates for an option by symbol, request type, and expiration.

Inputs: symbol (required), expiration (required), request_type (required), right, +1 more.

option_list_expirationsA

[FREE] List available expiration dates for an option symbol. Updated overnight.

Inputs: symbol (required).

option_list_strikesA

[FREE] List available strikes for an option symbol and expiration. Updated overnight.

Inputs: symbol (required), expiration (required).

option_list_symbolsA

[FREE] List all traded option underlying symbols. Updated overnight.

Inputs: no named parameters.

option_snapshot_greeks_allC

[PROFESSIONAL] Real-time greeks for all contracts on an expiration. Use expiration=* for all.