Metadata-Version: 2.5
Name: tradeiq-mcp
Version: 0.2.1
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 -- uvx tradeiq-mcp
```

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

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

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

Paste this prompt into Claude Code, Claude Desktop, Codex, Cursor or any
assistant that can run commands or edit files on your computer, and it will do
the setup for you:

```text
Install the TradeIQ MCP server on my computer. It is a Python package on PyPI
named `tradeiq-mcp`, launched over stdio with the command `uvx tradeiq-mcp`.
Work out which assistant/client you are, then:

1. Check that `uv` is installed by running `uv --version`. If it is missing,
   install it: `pip install uv` works everywhere; alternatives are
   `winget install --id=astral-sh.uv -e` (Windows) or
   `curl -LsSf https://astral.sh/uv/install.sh | sh` (macOS/Linux). If `uvx`
   is not on PATH afterwards, use the full path to `uvx` in the steps below.

2. Register an MCP server named `tradeiq` that runs `uvx` with the argument
   `tradeiq-mcp`, at user/global scope, using your own client's method:
   - Claude Code: `claude mcp add tradeiq -s user -- uvx tradeiq-mcp`
   - Claude Desktop: add `"tradeiq": {"command": "uvx", "args": ["tradeiq-mcp"]}`
     under `mcpServers` in claude_desktop_config.json (Windows:
     %APPDATA%\Claude\; macOS: ~/Library/Application Support/Claude/).
   - Codex CLI: `codex mcp add tradeiq -- uvx tradeiq-mcp`
   - Cursor: add the same entry under `mcpServers` in ~/.cursor/mcp.json.
   - Any other client: add the same command and args to its MCP config.
   Back up any config file before editing it, keep all my existing servers,
   and change nothing else.

3. Do not ask me for API keys or put any in the config: the data tools need
   none. (Optional, only if I ask later: FRED_API_KEY for macro data, or an
   LLM provider key for the optional analysis pipeline.)

4. Tell me exactly what you changed, that I need to fully restart the client,
   and how to check it worked: after restarting, ask for the latest verified
   market snapshot for AAPL.

If you cannot run commands or edit files yourself, give me the exact steps
for my client instead of guessing.
```

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