Finance MCP

An MCP server that gives an AI assistant read access to your real brokerage account and the market around it — and gives you, not the assistant, the only button that sends an order.

38 tools over Webull, Saxo, IBKR, Yahoo Finance, SEC EDGAR, BLS, the Federal Reserve and the BEA, plus a Streamlit dashboard that is the sole path to execution. The list is filtered to what your broker can actually serve, so a given account sees 36 or 37 of them — and 28 with no broker at all, which is a working install, not a broken one.

The assistant can draft an order. It cannot place one. Drafts go to a local queue; sending requires a broker preview and your click in the dashboard. That path does not exist on the tool side, so no prompt can reach it.

Every tool declares this to the client rather than only to the reader: 32 of 36 are annotated read-only, one is destructive (cancel_order, which pulls a resting order). A client that respects MCP annotations can wave through a price lookup and stop on the one call that reaches the market.

What this can and cannot do with your account

Asking an unknown repository for brokerage credentials is the hardest trust ask in software, so the answer is here rather than forty paragraphs down.

• There is no execution path on the tool side. Not gated, not guarded — absent. draft_order writes to a local queue. Sending needs a broker preview and your click in the dashboard, which no prompt can reach.
• Twenty-eight of the 38 tools never touch a broker. SEC filings, macro, indicators, options maths, earnings. With no credentials at all you get those twenty-eight, and that is a working install rather than a degraded one.
• Two of the three adapters have never been run. Saxo and Interactive Brokers are built from published API references and have not been executed against a live or paper account. They say so in every tool output that uses them. Only Webull has been run against a real account.
• The dashboard's submit button is Webull-only. The MCP tools route through the broker protocol; that one button does not, yet.
• Use a read-scoped key where your broker offers one. Nothing outside the dashboard needs write access.

1,431 tests across 32 files, and CI runs them on every push.

Those all stub the network, which is correct — a suite that goes red because SEC returned a 503 overnight is a suite nobody reads. It is also why two defects survived every one of them: a euro-area series that had stopped publishing eight months earlier and was reported as current, and a filing watcher that answered 403 to every request and called itself healthy. Both needed the real internet to see. tests/test_live_sources.py asks every external source for real and checks that this tool's account of the answer is true — in particular that a series marked fresh actually is. It is opt-in and skipped by default:

FINANCE_LIVE_SOURCES=1 pytest tests/test_live_sources.py -v -s

It also runs weekly in CI, because a check that depends on somebody remembering is a check that eventually stops happening — and discontinued series and broken scrapers are exactly the failures that arrive quietly over weeks. That workflow is inert until FRED_API_KEY and SEC_USER_AGENT exist as repository secrets, and when they do not it says so in the job summary rather than reporting a green tick that verified nothing.

Candles with overlays, a volume pane and the forecast cone. Weekends and market holidays are collapsed, so there are no blank stretches.

What it does

What you need

Installation guide → — fifteen minutes, most of it waiting for free API keys.

This places real orders against a real account. The consensus score is a fixed-weight heuristic that underperformed buy-and-hold in backtest and is labelled as such throughout. Not financial advice — see NOTICE.md for the full disclaimers and the third-party data terms.

Brokers

Both unverified adapters say so in every tool output that uses them, and refuse rather than guess on the paths the docs did not pin down.

dashboard/broker_protocol.py is the interface; tests/test_broker_conformance.py runs the same suite against every adapter. FINANCE_BROKER=ibkr selects which adapter the protocol and the MCP tools report through.

What works with which broker

28 of the 38 tools are broker-agnostic — indicators, options, SEC filings, insider and institutional data, earnings, macro. They work the same whoever you clear through, though the prices underneath them now come from your broker where it serves bars (see below).

Eight are account and order tools, and they go through broker_protocol.py, so they work with any adapter that declares the capability they need:

A tool is only registered when the configured broker can serve it. Start with FINANCE_BROKER=saxo and cancel_order is not in tools/list at all — Saxo cancels by its own order id and documents no mapping from ours, so a cancel tool would be a tool that can only refuse. An unusable tool costs a model context on every request and is one more wrong choice available to it.

The same rule covers having no broker. Every adapter constructs lazily, so that listing tools never opens a socket — which meant an empty .env built a broker object quite happily and all eight account tools were offered to someone who could not call a single one of them. They now check for their credentials offline and register only if they have them, so a broker-free install lists 28 tools that all work rather than 36 of which eight cannot. Where the answer is genuinely unknowable offline — IBKR's Client Portal Gateway holds the session after a browser login and wants no token at all — the tools stay registered, because hiding a tool that would have worked leaves nobody a way to find out why.

Two more exist only for the broker that has them: saxo_corporate_actions (dividends, splits, tenders and their election deadlines — Saxo is the only one of the three with them) and ibkr_market_scanner (the exchange-side scan, rather than inferring rotation from eleven ETF price pulls).

Capability is resolved per account, not per broker name, because three different things have to line up:

capability = what the SDK implements
           ∩ what the regional entity serves
           ∩ what this account is entitled to

Read the full README on GitHub →