Metadata-Version: 2.5
Name: tradeiq-mcp
Version: 0.2.2
Summary: Standalone MCP server: real point-in-time market data and a multi-agent equity research pipeline as tools for Claude, Codex, and other MCP clients.
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: claude,equity-research,market-data,mcp,model-context-protocol,stocks,trading
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Requires-Dist: langchain-anthropic>=0.3.15
Requires-Dist: langchain-core>=0.3.81
Requires-Dist: langchain-google-genai>=4.0.0
Requires-Dist: langchain-openai>=0.3.23
Requires-Dist: langgraph-checkpoint-sqlite>=2.0.0
Requires-Dist: langgraph>=0.4.8
Requires-Dist: markdown-it-py>=3.0.0
Requires-Dist: markdown>=3.7
Requires-Dist: matplotlib>=3.9
Requires-Dist: mcp[cli]>=1.2.0
Requires-Dist: mplfinance>=0.12.10b0
Requires-Dist: pandas>=2.3.0
Requires-Dist: python-docx>=1.1.2
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pytz>=2025.2
Requires-Dist: requests>=2.32.4
Requires-Dist: stockstats>=0.6.5
Requires-Dist: typing-extensions>=4.14.0
Requires-Dist: weasyprint>=70.0
Requires-Dist: yfinance>=1.4.1
Provides-Extra: bedrock
Requires-Dist: langchain-aws>=1.5.0; extra == 'bedrock'
Description-Content-Type: text/markdown

# 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`](https://docs.astral.sh/uv/). Then add the server to your client:

**Claude Code**

```bash
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`):

```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**

```bash
codex mcp add tradeiq -- uvx tradeiq-mcp
```

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

```text
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.

```text
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

```text
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

```text
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)

```text
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

```text
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:

```bash
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 (override with `TRADINGAGENTS_RESULTS_DIR`
and `TRADINGAGENTS_MEMORY_LOG_PATH`). The server has no backend of its own to
send them to; its outbound requests go to the market-data sources the tools
query, and to your LLM provider if you use the optional pipeline.

## 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

```bash
python -m venv .venv
.venv/bin/python -m pip install -e .      # Windows: .venv\Scripts\python.exe
.venv/bin/python scripts/smoke_test.py    # exercises the tools end to end
```

## Third-party code

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

## License

Apache-2.0 — see `LICENSE`.
