Ko MCP

ko.io — Wall Street data feed for AI agents

One command connects Claude, Cursor, Windsurf, Zed, Codex, and any MCP client to 100M+ source-traced SEC records. Every answer traces to a real filing.

Website · Docs · MCP Setup · Get a free key · Pricing

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.

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

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

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:

Plans

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