TradingAgents MCP

A local MCP server and research skill for Codex and Claude Code, built on the upstream TradingAgents Python library. Use it to research stocks and crypto, check options strategies, and save reports and decision history.

uv installs the pinned TradingAgents dependency in the project's .venv. Codex launches server.py as a local MCP server over standard input and output. The server imports TradingAgents and exposes selected capabilities as MCP tools, including market data, options calculations, and report storage. The trading-analysis skill guides the client through the research workflow. The original TradingAgents pipeline is also available with separate model sign-in.

For research. This is an independent project. See NOTICE for upstream attribution.

Install

Codex

Install the Codex CLI, sign in with your own account, and install uv. Clone this repository and run the following from its root on macOS or Linux. If you already have a trading-analysis skill link, check that it points to this checkout and skip the ln -s command if it does.

uv sync --frozen --no-dev
codex mcp add tradingagents \
  --env "TRADINGAGENTS_ENV_FILE=$PWD/.env.codex" \
  --env TRADINGAGENTS_FRONTEND=Codex \
  -- "$(command -v uv)" run --directory "$PWD" --frozen --no-dev --quiet python server.py

mkdir -p "$HOME/.codex/skills"
ln -s "$PWD/skills/trading-analysis" "$HOME/.codex/skills/trading-analysis"
codex mcp list

Open the checkout in a fresh Codex chat and ask it to use TradingAgents to fetch an NVDA market snapshot. Your existing Codex sign-in is enough for this workflow.

Optional original TradingAgents pipeline

To run the upstream pipeline with an eligible ChatGPT Plus or Pro plan, create .env.codex from the provided example and complete the separate TradingAgents sign-in. Usage counts against your plan.

test -f .env.codex || cp .env.codex.example .env.codex
.venv/bin/tradingagents login chatgpt

In ~/.codex/config.toml, add tool_timeout_sec = 660 to the existing [mcp_servers.tradingagents] section so pipeline_wait has time to finish. To require confirmation for backtests, add the following at the end of the file. Open a fresh Codex chat after setup.

[mcp_servers.tradingagents.tools.run_backtest]
approval_mode = "prompt"

Optional read-only Robinhood connection

Robinhood hosts a separate MCP server. To enable the documented read-only tools for external agents, add this entry to ~/.codex/config.toml, or update the existing robinhood entry. Trim the list to the tools you want Codex to access.

[mcp_servers.robinhood]
url = "https://agent.robinhood.com/mcp/trading"
enabled_tools = [
    # Account and portfolio
    "get_accounts",
    "get_portfolio",
    "get_realized_pnl",
    "get_pnl_trade_history",
    "search",
    "get_limited_margin_upgrade_info",
    "get_trade_approvals",
    "get_trade_approval_setting",
    # Watchlists
    "get_watchlists",
    "get_watchlist_items",
    "get_option_watchlist",
    "get_popular_watchlists",
    # Market data
    "get_equity_historicals",
    "get_equity_fundamentals",
    "get_financials",
    "get_equity_price_book",
    "get_equity_technical_indicators",
    "get_earnings_results",
    "get_earnings_calendar",
    "get_indexes",
    "get_index_quotes",
    "get_sec_filing_index",
    "get_sec_filing",
    "get_sec_filing_facts",
    "get_sec_filing_facts_catalog",
    "get_index_historicals",
    "get_politician_trades",
    "get_equity_analyst_ratings",
    # Equities
    "get_equity_positions",
    "get_equity_tax_lots",
    "get_equity_quotes",
    "get_equity_orders",
    "get_equity_tradability",
    # Options
    "get_option_level_upgrade_info",
    "get_option_chains",
    "get_option_historicals",
    "get_option_instruments",
    "get_option_quotes",
    "get_option_positions",
    "get_option_orders",
    # Crypto
    "get_currency_pairs",
    "get_crypto_quotes",
    "get_crypto_positions",
    "get_crypto_orders",
    "get_crypto_account_onboarding_info",
    "get_crypto_tax_lots",
    # Scanners
    "get_scans",
    "get_scanner_filter_specs",
    "run_scan",
    "get_scanner_datapoints",
    "preview_scan",
    # Alerts
    "get_alerts",
    "get_alert_log",
    # Advanced order history
    "get_advanced_orders",
    # Legend
    "get_legend_charts",
    "get_legend_indicators",
    "get_legend_indicator_catalog",
    "get_legend_layouts",
]

Run the login command, authorize your own Robinhood account in the browser, then open a fresh Codex chat. See Robinhood's onboarding instructions.

codex mcp login robinhood

Account-specific reads use a brokerage account number. With get_accounts enabled, Codex can look up your linked accounts. The allowlist includes portfolio and position reads, order history, market data, watchlists, scanner results, alerts, and Legend data. Actual availability depends on the tools Robinhood advertises to your signed-in session. Trade submission, cancellation, exercises, order previews, transfers, and changes to saved settings are outside this allowlist. See Robinhood's external-agent tool reference.

Claude Code

Install Claude Code and uv. In Claude Code, add the local checkout as a marketplace and install the plugin using its existing marketplace name.

/plugin marketplace add /path/to/tradingagents-mcp
/plugin install tradingagents@tradingagents-claude

Restart Claude Code. On the first start, the plugin downloads TradingAgents and its Python dependencies, which takes about a minute. If its tools are missing in that first session, run /mcp and reconnect tradingagents.

Related MCP server: Financial Risk MCP Server

Use

Analyse NVDA

Run trading analysis on RELIANCE.NS, quick depth. I hold 50 shares at ₹2,400.

Settle my past trading decisions

What's NVDA's implied move into earnings? Price a covered call for my 200 shares.

Depth options

• quick: about 5 subagents. The main agent writes the debate, risk views, and a short fact check.

• standard (the default): about 13 subagents

• deep: adds a second debate round

Options

These work for listed options, mostly US, using Yahoo's live chains, so today only. Yahoo has no NSE/BSE options. Every figure is computed in code:

• options_overview: IV term structure, implied move per expiry, 25-delta skew, put/call open interest, max pain, realized volatility, next earnings date

• options_chain: one expiry's near-the-money strikes, with Black-Scholes deltas and the largest open-interest strikes

• options_strategy: prices a position from the live quotes: net debit/credit, max profit/loss, breakevens, probability of profit, net delta

The Options Strategist proposes defined-risk structures only and prices each one with options_strategy.

Fact check

Before the portfolio manager decides, a Fact Checker re-fetches the 15–30 figures the decision rests on and marks each one verified, wrong (with the correct value) or unsupported. The portfolio manager ignores anything wrong or unsupported. The check is saved as its own report section.

From your phone: start a Claude Code session on your computer, turn on Remote Control, and open the session in the Claude mobile app.

Two engines

Pipeline commands

Ask in plain words:

Run the pipeline on NVDA with 2 debate rounds

Backtest NVDA and AAPL weekly from June to September

Settle my past decisions

Each pipeline job takes about 3–10 minutes. After a pipeline run, the skill uses annotate_report to add fact check and options sections.

Jobs run inside the MCP server, so keep the Codex or Claude Code session open until a job finishes. If you close it, ask again and the run resumes from its checkpoint. While a job runs, the server keeps your Mac awake with caffeinate. A closed lid still sleeps. Set TA_MCP_KEEP_AWAKE=0 to turn this off.

Backtests cost one full pipeline run per cell (tickers × dates). They are refused above max_cells (default 12), so you have to confirm a larger grid. They use a memory log of their own, never your live one.

Either engine

• list_reports and read_report: past analyses from both engines

• annotate_report: adds or replaces the Options and Fact Check sections of a saved report

• backtest_results: past backtest scorecards, read at no cost

Configure (optional)

Copy .env.example to .env in this folder. It's gitignored, so keys never get committed. Settings load in this order, and the first file to set a value wins:

1. The file named by TRADINGAGENTS_ENV_FILE (Codex uses .env.codex)

2. <repo>/.env

3. ~/.tradingagents/.env (use this for a plugin installed from GitHub, whose folder is replaced on update)

Useful settings:

• SEC_EDGAR_USER_AGENT: your name and email. SEC asks callers to identify themselves.

• FRED_API_KEY: free; adds US macro data (rates, CPI, yields).

• ANTHROPIC_API_KEY plus the model settings: turns on the full pipeline.

Where things are saved

• Reports: ~/.tradingagents/logs/reports/<TICKER>_<time>/complete_report.{md,html}

• Decision memory: ~/.tradingagents/memory/trading_memory.md

• Pipeline jobs: ~/.tradingagents/mcp_jobs/

Data

Market data comes from TradingAgents' sources:

• Yahoo Finance

• SEC EDGAR (US filings as originally filed)

• StockTwits and Reddit

• FRED

• Polymarket

Every dated tool takes an analysis date and never returns data published after it.

Some sources only have live data: the fundamentals profile, insider trades, StockTwits, Polymarket, most news and all options data. These are withheld for past dates, so analyses dated today have the fullest data.

Stocks work on any exchange Yahoo covers (RELIANCE.NS, 0700.HK, AZN.L, …), and crypto works as BTC-USD.

Develop

From the cloned repository root, install the development dependencies and run the checks.

uv sync --frozen
uv run pytest
uv run python tests/smoke_stdio.py

TradingAgents is pinned to v0.7.1 in pyproject.toml and uv.lock. To upgrade, change the tag, run uv lock, run the tests, then bump the version in both manifests.

License

Apache 2.0. See LICENSE and NOTICE.