ko-mcp

30-second start

In an AI agent (MCP) — works instantly, no key needed:

claude mcp add ko-sec-data --transport http https://mcp.ko.io/mcp

Then ask: "who is buying NVDA?", "what did Congress trade last month?", "which institutions hold spot BTC ETFs?" — the agent calls real tools and cites real filings.

Over REST — keyless demo mode:

curl "https://api.ko.io/api/v1/institutions?search=berkshire&demo=true"

In Python:

pip install ko-edgar

from ko_edgar import KoClient

ko = KoClient()  # demo mode; KoClient(api_key="ko_live_...") for your quota
for h in ko.stocks.holders("NVDA"):
    print(h["name"], h["holding_value"], h["action"])

In TypeScript:

npm install @ko-io/sdk

import { KoClient } from "@ko-io/sdk";

const ko = new KoClient(); // or { apiKey: "ko_live_..." }
const { rows } = await ko.congress.trades({ sort: "recent" });

Free keys are 200 calls/day, forever, no credit card → ko.io/console.

What's in this repo

Browse the documentation index for setup guides, package docs, and contributor workflows.

Directory	What it is
server/	The hosted MCP server (mcp.ko.io) — Cloudflare Worker, 32 tools, deployed from this repo
docs/clients/	Verified setup guides for every MCP client
python/	ko-edgar — official Python SDK (sync + async, typed)
typescript/sdk/	@ko-io/sdk — official TypeScript SDK (Node 18+, browsers, edge)
typescript/mcp-proxy/	@ko-io/mcp-sec-data — stdio bridge for clients without remote-HTTP MCP support
cookbook/	10 runnable answers to real investing questions
llms.txt	Machine-readable map of every tool and endpoint

The MCP server in server/ is the exact code running at https://mcp.ko.io/mcp — every push to main that touches server/ deploys it. You can also self-host it on your own Cloudflare account (cd server, drop the routes block in wrangler.toml — it is pinned to the ko.io zone — then npx wrangler deploy); it proxies to api.ko.io with your API key, so your quota and plan follow you. The data pipelines behind the API run as a managed service (dual-region, 3-replica ClickHouse, 27 pipelines refreshing on each source's publication schedule).

Note: all three client packages are published — ko-edgar on PyPI, and @ko-io/sdk and @ko-io/mcp-sec-data on npm. The hosted MCP endpoint and REST API work today.

Connect your client

Client	Guide	One-liner
Claude Code	guide	claude mcp add ko-sec-data --transport http https://mcp.ko.io/mcp
Claude Desktop	guide	remote HTTP config or npx -y @ko-io/mcp-sec-data
Cursor	guide	~/.cursor/mcp.json
Windsurf	guide	Cascade → MCP
Zed	guide	context_servers in settings
OpenAI Codex	guide	codex mcp add ko-sec-data --url https://mcp.ko.io/mcp
ChatGPT / Gemini / Grok	guide	REST API / Custom GPT Actions

To use your own quota in any client, append ?api_key=YOUR_KEY to the server URL, or send Authorization: Bearer YOUR_KEY.

The data

Dataset	Coverage	Free tier
13F institutional holdings	88M+ rows, 2013 → today, family-consolidated	✅
Insider trades (Forms 3/4/5)	11M+ transactions, open-market classified	✅
Congress trading	STOCK Act disclosures, both chambers	✅
Crypto ETF exposure	Institutional spot-BTC-ETF holdings from 13F	✅
Form 144	Planned insider sales (forward-looking)	✅
Fails-to-deliver + Reg SHO	Short-side stress footprints	✅
Stock prices & financials	Daily OHLCV + XBRL-derived 10-K/10-Q statements incl. cash, capex, free cash flow, buybacks, dividends	✅
SEC filings gateway	Any filing document, signed shareable links	list/index ✅ · documents Pro
Macro (Treasury, Fed, CPI, OFR stress)	Daily federal sources	Pro
European disclosures (SE, NL, DK, UK)	Insider dealings (PDMR), major holdings, net short positions (not UK), annual reports; per-row source credit. Live: all four since 2026-10-17 (UK has no short positions) -- get_eu_markets shows what is live	✅ (trailing window)

All data is source-traced through the pipeline, and the filings gateway can pull the underlying SEC documents — so your agent cites real filings instead of inventing numbers.

The 32 MCP tools

Institutions: get_institution_holdings · list_institutions · Stocks: get_stock_profile · get_stock_holders · get_stock_activity · get_stock_price · get_stock_financials · Insiders: get_insider_trades · list_insider_traders · Congress: get_congress_trades · get_congress_member · Government contracts: get_gov_contracts · search_gov_contracts · Crypto: get_crypto_exposure · get_crypto_holders · get_crypto_holder · Filings: sec_list_filings · sec_get_filing_index · sec_get_filing_document · Short data: get_ftd_data · Search: search · Form 144: get_form144_notices · Macro (Pro): get_treasury_yields · get_fed_rates · get_economic_indicators · get_financial_stress · Europe: get_eu_markets · get_eu_insider_dealings · get_eu_major_holdings · get_eu_short_positions · get_eu_annual_reports · get_eu_issuer

Full parameter reference: llms.txt · ko.io/docs

Company financials

get_stock_financials returns 10-K/10-Q statement values: revenue, net income, EPS, margins, operating cash flow, cash_and_equivalents, total_assets, total_liabilities, capex, free_cash_flow, stock_repurchase (buybacks), dividends_paid, investing_cashflow, financing_cashflow and debt. Capex, buybacks and dividends are each normally a positive cash payment (USD); negative values are passed through as filed or derived; a negative capex makes free_cash_flow null. free_cash_flow = operating_cashflow - capex only when both are reported and capex >= 0; otherwise null (a missing value is never read as 0). cash_and_equivalents excludes short-term investments; long_term_debt is us-gaap LongTermDebt, which includes the current portion. Example: "MSFT buybacks last 4 quarters" -> get_stock_financials(ticker="MSFT", period_type="quarterly", limit=4). Free and keyless calls return the latest quarter only; earlier quarters and annual statements require Pro.

Government contracts

get_gov_contracts returns issuer-level U.S. federal prime-contract obligations since FY2015. Use include=actions for action rows or award_id for one award's attributed actions. search_gov_contracts searches actions across companies or ranks companies with view=companies. Amounts remain exact decimal strings. Gross is positive obligations; deobligations are negative; net is their sum. Free access covers the trailing 92 days. History requires Pro. Choose one window: period, fiscal_year, or from/to. Automatic exact matches cover companies listed today, plus reviewed links with recorded evidence. No linked actions does not prove no contracts. Recent months are provisional; Defense reports about 90 days late. See the methodology.

Why not scrape EDGAR directly?

Excellent open-source tools exist for pulling raw filings from SEC EDGAR (e.g. sec-edgar-mcp — if you need one company's raw documents in a local process, it's a fine choice). ko.io solves a different problem — the questions raw EDGAR can't answer:

	Raw EDGAR access	ko.io
"Get AAPL's latest 10-K"	✅	✅ (filings gateway)
"Who is buying NVDA across all institutions?"	❌ needs every 13F parsed	✅ 122ms
"Berkshire's portfolio, 52 quarters back"	❌ parse 50+ filings live	✅ precomputed
"Vanguard's 7 filing entities as one manager"	❌	✅ family consolidation
Congress trades, FTD, macro, crypto exposure	❌ not in EDGAR	✅
Works in web-based AI (claude.ai, ChatGPT)	❌ local process	✅ hosted MCP
Setup	Python env + install	one command, zero install

Plans

	Demo (no key)	Free	Pro	Builder
Calls/day	limited	200	20,000	200,000
Rows/request	500	500	5,000	50,000
Core SEC data	✅	✅	✅	✅
History depth	latest	latest	full	full
Macro (Treasury/Fed/CPI/stress)	—	—	✅	✅
Bulk export	—	—	—	✅

Quota resets 00:00 UTC. MCP and REST share one quota. Prices: https://ko.io/pricing/

Contributing

Issues and PRs welcome — see CONTRIBUTING.md. Security reports: SECURITY.md.

MIT © ko.io