tradeiq-mcp

An MCP (Model Context Protocol) server that gives Claude, Codex CLI and other MCP clients real, point-in-time market data — prices, indicators, fundamentals, SEC filings, news, insider activity, options, earnings dates, macro series — plus tools to turn an analysis into a professionally formatted report (PDF, HTML, Word or Markdown) and to keep a verifiable track record of your calls.

It runs locally on your machine over stdio. No account and no hosted backend of its own; most data tools need no API key (macro series need a free FRED key).

Educational and informational use only. Nothing here is investment advice.

Install

You need uv. Then add the server to your client:

Claude Code

claude mcp add tradeiq -s user -- uvx tradeiq-mcp

(-s user makes it available in every project, not just the current folder.)

Claude Desktop — add to claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "tradeiq": { "command": "uvx", "args": ["tradeiq-mcp"] }
  }
}

If Claude Desktop can't find uvx (it's a GUI app and may not see your terminal's PATH), put the full path to uvx in command instead — see where uvx (Windows) or which uvx (macOS).

Codex CLI

codex mcp add tradeiq -- uvx tradeiq-mcp

The first launch downloads the dependencies (about a minute). If your client times out on it (Codex's default is 10 seconds), pre-warm once with uvx tradeiq-mcp --version, then start the client.

Restart the client, then ask for something like "Research MSFT and give me a full report as a PDF."

Prefer pip? pip install tradeiq-mcp, then use tradeiq-mcp as the command.

Or let your AI assistant install it

Copy the prompt for the client you use and paste it into that client's chat. Each prompt is self-contained and names the exact commands, file paths and checks for that client. They all begin by pre-warming the download: the first run fetches about 120 packages, and some clients give up on a server that takes more than a few seconds to start.

Clients that only accept remote (hosted) MCP servers, which includes most web chat apps, can't run this one, because it runs locally over stdio.

The Claude Code prompt has been tested end to end. The others follow each client's documented MCP configuration format, but haven't been run on every operating system. If a step fails, each prompt tells the assistant to report the error instead of guessing.

Claude Code

Install the TradeIQ MCP server for Claude Code on this computer. TradeIQ is a
Python package on PyPI called `tradeiq-mcp`; it runs locally over stdio and is
launched with `uvx tradeiq-mcp`. Do these steps in order, and stop and tell me
if any step fails.

1. Run `uv --version`. If `uv` is missing, install it with `pip install uv`
   (or `winget install --id=astral-sh.uv -e` on Windows, or
   `curl -LsSf https://astral.sh/uv/install.sh | sh` on macOS/Linux). Then run
   `uvx --version`. If `uvx` is not found on PATH, find its full path (pip puts
   it in the user Scripts/bin folder) and use that full path instead of `uvx`
   in every step below.

2. Pre-warm the download so the first launch is not slow (the package pulls in
   about 120 dependencies). Run:
   uvx --from tradeiq-mcp python -c "import tradeiq_mcp; print('ready')"
   and wait for it to print `ready`. This can take a few minutes the first time.

3. Run `claude mcp list`. If a `tradeiq` server already exists, remove it with
   `claude mcp remove tradeiq -s user`. Then register it for all my projects:
   claude mcp add tradeiq -s user -- uvx tradeiq-mcp
   (use the full path to uvx if step 1 required it).

4. Run `claude mcp list` and confirm `tradeiq` shows Connected. If it shows a
   failure, run step 2 again and re-check before doing anything else.

5. Do not ask me for API keys and do not add any: the data tools need none.
   Optional extras only if I ask later: FRED_API_KEY (macro data), or an LLM
   provider key for the optional analysis pipeline (add it with `-e KEY=value`
   on the `claude mcp add` command).

6. Tell me exactly what you changed. Then tell me to restart Claude Code and
   test with: "Get the latest verified market snapshot for AAPL."

If you cannot run commands yourself, do not guess: give me the exact commands
to run by hand.

Claude Desktop

Claude Desktop's chat can't edit files or run commands on its own. If you haven't enabled a file or command tool for it, paste this prompt and it will give you the exact steps to do by hand, or paste it into Claude Code instead.

Install the TradeIQ MCP server for the Claude Desktop app on this computer.
TradeIQ is a Python package on PyPI called `tradeiq-mcp`; it runs locally over
stdio and is launched with `uvx tradeiq-mcp`. Do these steps in order, and stop
and tell me if any step fails.

1. Make sure `uv` is installed: run `uv --version`. If it is missing, install
   it with `pip install uv` (or `winget install --id=astral-sh.uv -e` on
   Windows, or `curl -LsSf https://astral.sh/uv/install.sh | sh` on macOS).

2. Find the FULL path to `uvx` (`where uvx` on Windows, `which uvx` on macOS;
   if it is not on PATH, look in the folder pip or uv installed it to). Use this
   full path, not the bare word `uvx`, because Claude Desktop is a GUI app and
   often does not inherit the PATH your terminal has. On Windows write the path
   with forward slashes (C:/Users/me/.../uvx.exe) so it needs no JSON escaping.

3. Pre-warm the download: run
   <full path to uvx> --from tradeiq-mcp python -c "import tradeiq_mcp; print('ready')"
   and wait for `ready`. The first time this takes a few minutes because the
   package pulls in about 120 dependencies.

4. Open the Claude Desktop config file:
   - Windows: %APPDATA%\Claude\claude_desktop_config.json
   - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   If it does not exist, create it containing {"mcpServers": {}}. Make a backup
   copy first. Add this entry inside "mcpServers" and keep every server that is
   already there:
     "tradeiq": {
       "command": "<full path to uvx>",
       "args": ["tradeiq-mcp"]
     }
   Check the file is still valid JSON afterwards (commas, braces, quotes).

5. Do not ask me for API keys and do not add any: the data tools need none.
   (Optional, only if I ask later: an "env" object on that entry holding
   FRED_API_KEY for macro data, or an LLM provider key for the optional
   analysis pipeline.)

6. Tell me exactly what you changed. Then tell me to fully quit Claude Desktop
   (on Windows also from the system tray, not just by closing the window) and
   reopen it. To verify: Settings > Developer should list `tradeiq` as running,
   and asking "Get the latest verified market snapshot for AAPL" should call it.
   If it shows an error there, open Claude's log folder, find the
   mcp-server-tradeiq log, and tell me what it says.

If you cannot run commands or edit files yourself, do not guess: give me the
exact steps and the exact file contents to do it by hand.

Codex CLI

Install the TradeIQ MCP server for Codex CLI on this computer. TradeIQ is a
Python package on PyPI called `tradeiq-mcp`; it runs locally over stdio and is
launched with `uvx tradeiq-mcp`. Do these steps in order, and stop and tell me
if any step fails.

1. Run `uv --version`. If `uv` is missing, install it with `pip install uv`
   (or `winget install --id=astral-sh.uv -e` on Windows, or
   `curl -LsSf https://astral.sh/uv/install.sh | sh` on macOS/Linux). If `uvx`
   is not on PATH afterwards, find its full path and use that instead of `uvx`
   in every step below.

2. Pre-warm the download. This matters more for Codex than for other clients,
   because Codex stops waiting for an MCP server after 10 seconds by default.
   Run:
   uvx --from tradeiq-mcp python -c "import tradeiq_mcp; print('ready')"
   and wait for `ready` (a few minutes the first time; about 120 dependencies).

3. Register the server:
   codex mcp add tradeiq -- uvx tradeiq-mcp
   (full path to uvx if step 1 required it). If a `tradeiq` entry already
   exists in the config, update it instead of adding a duplicate.

4. Open ~/.codex/config.toml (Windows: %USERPROFILE%\.codex\config.toml). Back
   it up first. Make the `tradeiq` section read as follows, keeping everything
   else in the file unchanged:
   [mcp_servers.tradeiq]
   command = "uvx"
   args = ["tradeiq-mcp"]
   startup_timeout_sec = 120
   tool_timeout_sec = 300
   The longer timeouts matter: Codex defaults to 10 seconds to start a server
   and 60 seconds per tool call, and research reports can take longer than
   that. If step 1 needed a full path, put it in `command` (on Windows use
   forward slashes).

5. Run `codex mcp list` and confirm `tradeiq` is listed.

6. Do not ask me for API keys and do not add any: the data tools need none.
   Optional extras only if I ask later: FRED_API_KEY (macro data), or an LLM
   provider key for the optional analysis pipeline (add an `env` entry, or use
   `--env KEY=value` on `codex mcp add`).

7. Tell me exactly what you changed. Then tell me to start a new Codex session
   and check that `/mcp` shows `tradeiq` as active, then test with: "Get the
   latest verified market snapshot for AAPL."

If you cannot run commands or edit files yourself, do not guess: give me the
exact commands and file contents to do it by hand.

Cursor

Install the TradeIQ MCP server for Cursor on this computer. TradeIQ is a Python
package on PyPI called `tradeiq-mcp`; it runs locally over stdio and is launched
with `uvx tradeiq-mcp`. Do these steps in order, and stop and tell me if any
step fails.

1. Run `uv --version`. If `uv` is missing, install it with `pip install uv`
   (or `winget install --id=astral-sh.uv -e` on Windows, or
   `curl -LsSf https://astral.sh/uv/install.sh | sh` on macOS/Linux). Then find
   the FULL path to `uvx` (`where uvx` on Windows, `which uvx` on macOS/Linux).
   Use that full path in the config below: Cursor is a GUI app and may not
   inherit your terminal's PATH. On Windows use forward slashes in the path.

2. Pre-warm the download: run
   <full path to uvx> --from tradeiq-mcp python -c "import tradeiq_mcp; print('ready')"
   and wait for `ready` (a few minutes the first time; about 120 dependencies).

3. Open Cursor's global MCP config: ~/.cursor/mcp.json (Windows:
   %USERPROFILE%\.cursor\mcp.json). If it does not exist, create it containing
   {"mcpServers": {}}. Back it up first. Add this entry inside "mcpServers" and
   keep every server that is already there:
     "tradeiq": {
       "command": "<full path to uvx>",
       "args": ["tradeiq-mcp"]
     }
   Check the file is still valid JSON afterwards.

4. Do not ask me for API keys and do not add any: the data tools need none.
   (Optional, only if I ask later: an "env" object on that entry holding
   FRED_API_KEY for macro data, or an LLM provider key for the optional
   analysis pipeline.)

5. Tell me exactly what you changed. Then tell me to restart Cursor, open the
   MCP section of Cursor's settings (the Customize option in the sidebar) and
   make sure `tradeiq` is toggled on and lists its tools. If it errors, open the
   Output panel (Cmd/Ctrl+Shift+U), choose "MCP Logs" from the dropdown, and
   tell me what it says. Test with: "Get the latest verified market snapshot
   for AAPL."

If you cannot run commands or edit files yourself, do not guess: give me the
exact steps and file contents to do it by hand.

VS Code (GitHub Copilot)

Install the TradeIQ MCP server for VS Code (GitHub Copilot Chat, agent mode) on
this computer. TradeIQ is a Python package on PyPI called `tradeiq-mcp`; it runs
locally over stdio and is launched with `uvx tradeiq-mcp`. Do these steps in
order, and stop and tell me if any step fails.

1. Run `uv --version`. If `uv` is missing, install it with `pip install uv`
   (or `winget install --id=astral-sh.uv -e` on Windows, or
   `curl -LsSf https://astral.sh/uv/install.sh | sh` on macOS/Linux). If `uvx`
   is not on PATH afterwards, find its full path (`where uvx` / `which uvx`)
   and use that instead of `uvx` below (forward slashes on Windows).

2. Pre-warm the download: run
   uvx --from tradeiq-mcp python -c "import tradeiq_mcp; print('ready')"
   and wait for `ready` (a few minutes the first time; about 120 dependencies).

3. Add the server to my VS Code USER configuration so it is available in every
   workspace. Preferred: on macOS/Linux run
   code --add-mcp '{"name":"tradeiq","type":"stdio","command":"uvx","args":["tradeiq-mcp"]}'
   On Windows PowerShell the quoting is error-prone, so instead open the user
   config file: run "MCP: Open User Configuration" from the Command Palette (or
   edit the `mcp.json` in my VS Code user profile folder). Back it up first.
   Note that VS Code's file uses the top-level key "servers", not
   "mcpServers". Add this and keep every server already there:
     "servers": {
       "tradeiq": {
         "type": "stdio",
         "command": "uvx",
         "args": ["tradeiq-mcp"]
       }
     }
   Check the file is still valid JSON afterwards.

4. Do not ask me for API keys and do not add any: the data tools need none.
   (Optional, only if I ask later: an "env" object on that entry holding
   FRED_API_KEY for macro data, or an LLM provider key for the optional
   analysis pipeline.)

5. Tell me exactly what you changed. Then tell me to run "MCP: List Servers"
   from the Command Palette, pick `tradeiq`, choose Start Server (and Show
   Output if it fails), then open Copilot Chat in Agent mode and check that
   `tradeiq` tools appear in the tools picker. Test with: "Get the latest
   verified market snapshot for AAPL."

If you cannot run commands or edit files yourself, do not guess: give me the
exact steps and file contents to do it by hand.

Gemini CLI

Install the TradeIQ MCP server for Gemini CLI on this computer. TradeIQ is a
Python package on PyPI called `tradeiq-mcp`; it runs locally over stdio and is
launched with `uvx tradeiq-mcp`. Do these steps in order, and stop and tell me
if any step fails.

1. Run `uv --version`. If `uv` is missing, install it with `pip install uv`
   (or `winget install --id=astral-sh.uv -e` on Windows, or
   `curl -LsSf https://astral.sh/uv/install.sh | sh` on macOS/Linux). If `uvx`
   is not on PATH afterwards, find its full path and use that instead of `uvx`
   below (forward slashes on Windows).

2. Pre-warm the download: run
   uvx --from tradeiq-mcp python -c "import tradeiq_mcp; print('ready')"
   and wait for `ready` (a few minutes the first time; about 120 dependencies).

3. Open my user settings file ~/.gemini/settings.json (Windows:
   %USERPROFILE%\.gemini\settings.json). If it does not exist, create it as
   {}. Back it up first. Add this entry under the top-level "mcpServers" key,
   creating the key if needed, and keep everything already in the file:
     "tradeiq": {
       "command": "uvx",
       "args": ["tradeiq-mcp"]
     }
   Check the file is still valid JSON afterwards.

4. Do not ask me for API keys and do not add any: the data tools need none.
   (Optional, only if I ask later: an "env" object on that entry holding
   FRED_API_KEY for macro data, or an LLM provider key for the optional
   analysis pipeline.)

5. Tell me exactly what you changed. Then tell me to start a new `gemini`
   session, run `/mcp` to confirm `tradeiq` is connected and lists its tools,
   and test with: "Get the latest verified market snapshot for AAPL."

If you cannot run commands or edit files yourself, do not guess: give me the
exact commands and file contents to do it by hand.

How it works: your assistant does the thinking

Most tools here only fetch and verify data — there is no LLM inside them. The analysis (bull case, bear case, verdict) is written by the assistant you already use, on your own subscription, using verified data as input. That keeps this free to run and keeps every number traceable to a real source and date.

Every data tool takes an as_of_date and never returns anything after it, so an analysis "as of" a past date sees only what was actually knowable then. Live-only sources with no history (earnings calendar, options chains) are withheld for past dates rather than served mislabeled.

Tools

Data and research — no API key, no LLM cost

Tool	What it does
research_bundle	One call: verified snapshot, fundamentals, news and insider activity, pre-formatted as the first part of a report
get_price_history / get_technical_indicators	Daily OHLCV; RSI, MACD, Bollinger, moving averages, ATR
get_verified_market_snapshot	Deterministic price + indicator snapshot — the source of truth for an exact number
get_fundamentals / get_balance_sheet / get_cashflow / get_income_statement	Fundamentals and statements
get_sec_filed_financials	As-filed SEC EDGAR statements, point-in-time correct
get_ticker_news / get_global_news	Company and macro news
get_insider_transactions	Insider buys and sells
get_earnings_calendar	Next earnings date, estimates, dividend dates
get_options_snapshot	Near-the-money calls/puts, ATM implied volatility, put/call volume ratio
compare_tickers	Side-by-side valuation and technical table for 2–8 tickers
get_macro_indicators	FRED macro series (needs a free FRED_API_KEY)
get_prediction_markets	Polymarket odds for a topic
morning_briefing	Macro news, watchlist news and pending decisions in one call
normalize_ticker_symbol	Resolve broker-style symbols (XAUUSD → GC=F)

Reports and track record

Tool	What it does
save_report	Export a markdown report as PDF, HTML, Word or Markdown — cover page, contents, charts, color-coded sections
log_decision	Record a call (with its rating) in a persistent decision log
resolve_pending_decisions	Settle logged calls with the real realized return and alpha vs. a benchmark
get_track_record	Scorecard: hit rate and average alpha overall and per rating
list_recent_decisions / get_report	Read back past decisions and saved reports

Optional automated pipeline — needs your own LLM API key

Tool	What it does
analyze_ticker	Runs a multi-agent research debate for one ticker and date
run_backtest	Scores that pipeline's rating quality over a ticker × date grid
list_providers	Shows supported LLM providers and which have a key set

These make many LLM calls per run using your provider API key, set as an environment variable for the server (for example OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY). A Claude or ChatGPT subscription is not an API key and cannot be used for this. Everything else works without one.

Pass keys through your client's config, e.g. Claude Code:

claude mcp add tradeiq -e ANTHROPIC_API_KEY=... -- uvx tradeiq-mcp

Where data is written

Reports, exports and the decision log are written under ~/.tradingagents/ on your machine. The server has no backend of its own to send them to and collects no telemetry.

Setting (environment variable)	What it does
TRADINGAGENTS_RESULTS_DIR	Where reports and exports go (default ~/.tradingagents/logs)
TRADINGAGENTS_MEMORY_LOG_PATH	The decision log / track record file
TRADINGAGENTS_CACHE_DIR	Downloaded price and filing cache
FRED_API_KEY	Enables get_macro_indicators (free key from fred.stlouisfed.org)
SEC_EDGAR_USER_AGENT	Contact string sent to SEC EDGAR, e.g. "Your Name you@example.com" — SEC asks every automated client to identify itself, so please set this
Provider keys (OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, …)	Only for the optional paid pipeline

save_report only writes inside ~/.tradingagents/logs/exports or your home folder (never a hidden folder), only with the chosen format's extension, and never overwrites an existing file. Report text is treated as untrusted: exported HTML/PDF cannot run scripts or fetch remote content.

Note: a .env file in the folder your client starts the server from is read for the settings above, so keep unrelated secrets out of it.

Data sources and limits

Market data is fetched live from public sources: Yahoo Finance (through the unofficial yfinance library — prices, fundamentals, news, options), SEC EDGAR filings, FRED, Polymarket, and Reddit/StockTwits sentiment. Their own terms and rate limits apply to your use; heavy automated use can get an IP throttled. Yahoo data is delayed and unaudited, prices are split/dividend-adjusted, and values are in each instrument's own currency. Fundamentals, options and earnings dates are current snapshots and are withheld when you ask for a past date. This is research tooling for informational use, not investment advice; verify anything you rely on against primary sources.

PDF export on Linux and macOS

PDF export uses WeasyPrint, which needs the Pango system library on Linux and macOS (Linux: libpango-1.0-0 and libpangoft2-1.0-0; macOS: brew install pango). HTML, Word and Markdown export work without it, and the server starts either way.

Development

python -m venv .venv
.venv/bin/python -m pip install -e .      # Windows: .venv\Scripts\python.exe
.venv/bin/python -m pip install pytest
.venv/bin/python -m pytest tests          # offline tests
.venv/bin/python scripts/smoke_test.py    # end to end, needs network

Third-party code

This package bundles third-party open-source code under its own license. See NOTICE.

License

Apache-2.0 — see LICENSE.