io.github.SharpLu/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

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