{
  "markdown": "<div align=\"center\">\n\n# ko.io — Wall Street data feed for AI agents\n\n**One command connects Claude, Cursor, Windsurf, Zed, Codex, and any MCP client\nto 100M+ source-traced SEC records. Every answer traces to a real filing.**\n\n[![CI](https://github.com/SharpLu/ko-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/SharpLu/ko-mcp/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/ko-edgar)](https://pypi.org/project/ko-edgar/)\n[![npm](https://img.shields.io/npm/v/%40ko-io%2Fsdk)](https://www.npmjs.com/package/@ko-io/sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n[Website](https://ko.io) · [Docs](https://ko.io/docs) · [MCP Setup](https://ko.io/mcp) · [Get a free key](https://ko.io/console) · [Pricing](https://ko.io/pricing)\n\n<img src=\"assets/demo.svg\" alt=\"Claude querying NVDA institutional holders through the ko.io MCP server\" width=\"760\"/>\n\n</div>\n\n## 30-second start\n\n**In an AI agent (MCP)** — works instantly, no key needed:\n\n```bash\nclaude mcp add ko-sec-data --transport http https://mcp.ko.io/mcp\n```\n\nThen ask: *\"who is buying NVDA?\"*, *\"what did Congress trade last month?\"*,\n*\"which institutions hold spot BTC ETFs?\"* — the agent calls real tools and\ncites real filings.\n\n**Over REST** — keyless demo mode:\n\n```bash\ncurl \"https://api.ko.io/api/v1/institutions?search=berkshire&demo=true\"\n```\n\n**In Python**:\n\n```bash\npip install ko-edgar\n```\n\n```python\nfrom ko_edgar import KoClient\n\nko = KoClient()  # demo mode; KoClient(api_key=\"ko_live_...\") for your quota\nfor h in ko.stocks.holders(\"NVDA\"):\n    print(h[\"name\"], h[\"holding_value\"], h[\"action\"])\n```\n\n**In TypeScript**:\n\n```bash\nnpm install @ko-io/sdk\n```\n\n```ts\nimport { KoClient } from \"@ko-io/sdk\";\n\nconst ko = new KoClient(); // or { apiKey: \"ko_live_...\" }\nconst { rows } = await ko.congress.trades({ sort: \"recent\" });\n```\n\nFree keys are 200 calls/day, forever, no credit card → [ko.io/console](https://ko.io/console).\n\n## What's in this repo\n\n| Directory | What it is |\n|-----------|------------|\n| [`server/`](server) | **The hosted MCP server** (mcp.ko.io) — Cloudflare Worker, 24 tools, deployed from this repo |\n| [`docs/clients/`](docs/clients) | Verified setup guides for every MCP client |\n| [`python/`](python) | `ko-edgar` — official Python SDK (sync + async, typed) |\n| [`typescript/sdk/`](typescript/sdk) | `@ko-io/sdk` — official TypeScript SDK (Node 18+, browsers, edge) |\n| [`typescript/mcp-proxy/`](typescript/mcp-proxy) | `@ko-io/mcp-sec-data` — stdio bridge for clients without remote-HTTP MCP support |\n| [`cookbook/`](cookbook) | 10 runnable answers to real investing questions |\n| [`llms.txt`](llms.txt) | Machine-readable map of every tool and endpoint |\n\nThe MCP server in [`server/`](server) is the exact code running at\n`https://mcp.ko.io/mcp` — every push deploys it. You can also self-host it on\nyour own Cloudflare account (`cd server && npx wrangler deploy`); it proxies\nto `api.ko.io` with your API key, so your quota and plan follow you. The data\npipelines behind the API run as a managed service (dual-region, 3-replica\nClickHouse, 26 pipelines refreshing on each source's publication schedule).\n\n> **Note**: `ko-edgar` is live on PyPI (`pip install ko-edgar`). The npm packages\n> `@ko-io/sdk` and `@ko-io/mcp-sec-data` publish shortly. The hosted MCP endpoint\n> and REST API work today.\n\n## Connect your client\n\n| Client | Guide | One-liner |\n|--------|-------|-----------|\n| Claude Code | [guide](docs/clients/claude-code.md) | `claude mcp add ko-sec-data --transport http https://mcp.ko.io/mcp` |\n| Claude Desktop | [guide](docs/clients/claude-desktop.md) | remote HTTP config or `npx -y @ko-io/mcp-sec-data` |\n| Cursor | [guide](docs/clients/cursor.md) | `~/.cursor/mcp.json` |\n| Windsurf | [guide](docs/clients/windsurf.md) | Cascade → MCP |\n| Zed | [guide](docs/clients/zed.md) | `context_servers` in settings |\n| OpenAI Codex | [guide](docs/clients/codex.md) | `codex mcp add ko-sec-data --url https://mcp.ko.io/mcp` |\n| ChatGPT / Gemini / Grok | [guide](docs/clients/chatgpt-gemini-grok.md) | REST API / Custom GPT Actions |\n\nTo use your own quota in any client, append `?api_key=YOUR_KEY` to the server\nURL, or send `Authorization: Bearer YOUR_KEY`.\n\n## The data\n\n| Dataset | Coverage | Free tier |\n|---------|----------|-----------|\n| 13F institutional holdings | 85M+ rows, 2013 → today, family-consolidated | ✅ |\n| Insider trades (Forms 3/4/5) | 11M+ transactions, open-market classified | ✅ |\n| Congress trading | STOCK Act disclosures, both chambers | ✅ |\n| Crypto ETF exposure | Institutional spot-BTC-ETF holdings from 13F | ✅ |\n| Form 144 | Planned insider sales (forward-looking) | ✅ |\n| Fails-to-deliver + Reg SHO | Short-side stress footprints | ✅ |\n| Stock prices & financials | Daily OHLCV + XBRL-derived statements | ✅ |\n| SEC filings gateway | Any filing document, signed shareable links | list/index ✅ · documents Pro |\n| Macro (Treasury, Fed, CPI, OFR stress) | Daily federal sources | Pro |\n\nAll data is source-traced through the pipeline, and the filings gateway can\npull the underlying SEC documents — so your agent cites real filings instead\nof inventing numbers.\n\n## The 24 MCP tools\n\n**Institutions**: `get_institution_holdings` · `list_institutions` ·\n**Stocks**: `get_stock_profile` · `get_stock_holders` · `get_stock_activity` ·\n`get_stock_price` · `get_stock_financials` ·\n**Insiders**: `get_insider_trades` · `list_insider_traders` ·\n**Congress**: `get_congress_trades` · `get_congress_member` ·\n**Crypto**: `get_crypto_exposure` · `get_crypto_holders` · `get_crypto_holder` ·\n**Filings**: `sec_list_filings` · `sec_get_filing_index` · `sec_get_filing_document` ·\n**Short data**: `get_ftd_data` ·\n**Search**: `search` · **Form 144**: `get_form144_notices` ·\n**Macro (Pro)**: `get_treasury_yields` · `get_fed_rates` ·\n`get_economic_indicators` · `get_financial_stress`\n\nFull parameter reference: [llms.txt](llms.txt) · [ko.io/docs](https://ko.io/docs)\n\n## Why not scrape EDGAR directly?\n\nExcellent open-source tools exist for pulling raw filings from SEC EDGAR\n(e.g. [sec-edgar-mcp](https://github.com/stefanoamorelli/sec-edgar-mcp) — if\nyou need one company's raw documents in a local process, it's a fine choice).\nko.io solves a different problem — the questions raw EDGAR can't answer:\n\n| | Raw EDGAR access | ko.io |\n|---|---|---|\n| \"Get AAPL's latest 10-K\" | ✅ | ✅ (filings gateway) |\n| \"Who is buying NVDA across *all* institutions?\" | ❌ needs every 13F parsed | ✅ 122ms |\n| \"Berkshire's portfolio, 52 quarters back\" | ❌ parse 50+ filings live | ✅ precomputed |\n| \"Vanguard's 7 filing entities as one manager\" | ❌ | ✅ family consolidation |\n| Congress trades, FTD, macro, crypto exposure | ❌ not in EDGAR | ✅ |\n| Works in web-based AI (claude.ai, ChatGPT) | ❌ local process | ✅ hosted MCP |\n| Setup | Python env + install | one command, zero install |\n\n## Plans\n\n| | Demo (no key) | Free | Pro $29/mo | Team $99/mo |\n|---|---|---|---|---|\n| Calls/day | limited | 200 | 20,000 | 200,000 |\n| Rows/request | 500 | 500 | 5,000 | 50,000 |\n| Core SEC data | ✅ | ✅ | ✅ | ✅ |\n| History depth | latest | latest | full | full |\n| Macro (Treasury/Fed/CPI/stress) | — | — | ✅ | ✅ |\n| Bulk export | — | — | — | ✅ |\n\nQuota resets 00:00 UTC. MCP and REST share one quota. [Details →](https://ko.io/pricing)\n\n## Contributing\n\nIssues and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).\nSecurity reports: [SECURITY.md](SECURITY.md).\n\nMIT © ko.io\n",
  "bytes": 7447,
  "sha": "9e4c2041b4eb3618be9fe2ca960bfd7f34eb199a8389fac3de77ddf06474f3d2",
  "repo_slug": "sharplu/ko-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sharplu_ko_mcp_2fac7f61/readme"
}