Ko Mcp

io.github.SharpLuPublished by GitHub account SharpLuv1.0.0Updated Oct 24, 2026

Real SEC, 13F, insider, congress & macro data your AI agent can cite. Hosted MCP, 24 tools.

VerifiedStreamable HTTPWeb executableWeb Search & ScrapingFinanceData & Analytics

Overview

AI-generated overview

Hosted MCP server giving assistants source-traced SEC, 13F, insider, congressional, macro and European disclosure data for citable financial answers.

What you can do
  • Search institutions, stocks and insider traders, and pull institutional 13F holdings, stock profiles, holders, activity and price history
  • Retrieve insider Form 4 trades, Form 144 sale notices, fails-to-deliver data and congressional STOCK Act trades by member
  • List, index and fetch SEC EDGAR filings, with document links and optional text excerpts
  • Read company financials from 10-K/10-Q statements, U.S. Treasury yields, Fed rates, BLS indicators and the OFR stress index
  • Review crypto ETF institutional exposure and holders, U.S. federal contract obligations, and European insider, holdings, short-position and annual-report disclosures
When to use it
Useful when an assistant must answer investing, ownership, insider-activity, macro or regulatory-filing questions and cite real filings rather than guess. It fits research and analysis workflows in chat clients that support remote MCP, including web-based assistants.
Requirements
Remote streamable HTTP endpoint; no local install needed. Works keyless in a limited demo mode; a free or paid ko.io API key, passed as an api_key query parameter or an Authorization Bearer header, raises quota and unlocks history and macro data. Network access to the hosted endpoint is required.
Before you install
Keyless access is limited to the latest quarter and a small daily call count; full history, macro data and filing documents need a paid Pro plan. An API key in the URL query string can leak through logs or shared configs, so prefer the Authorization header. Quota is shared between MCP and REST calls. Data is informational and some recent figures are provisional.

Installation

In SourceWeft

  1. Open Ko Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.SharpLu%2Fko-mcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "ko": {
      "type": "http",
      "url": "https://mcp.ko.io/mcp"
    }
  }
}

README

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.

[CI] [PyPI] [npm] [License: MIT]

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

[Claude querying NVDA institutional holders through the ko.io MCP server]

30-second start

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

bash
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:

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

In Python:

bash
pip install ko-edgar
python
from ko_edgar import KoClient
ko = KoClient()  # demo mode; KoClient(api_key="ko_live_...") for your quotafor h in ko.stocks.holders("NVDA"):    print(h["name"], h["holding_value"], h["action"])

In TypeScript:

bash
npm install @ko-io/sdk
ts
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.

DirectoryWhat 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.txtMachine-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

ClientGuideOne-liner
Claude Codeguideclaude mcp add ko-sec-data --transport http https://mcp.ko.io/mcp
Claude Desktopguideremote HTTP config or npx -y @ko-io/mcp-sec-data
Cursorguide~/.cursor/mcp.json
WindsurfguideCascade → MCP
Zedguidecontext_servers in settings
OpenAI Codexguidecodex mcp add ko-sec-data --url https://mcp.ko.io/mcp
ChatGPT / Gemini / GrokguideREST 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

DatasetCoverageFree tier
13F institutional holdings88M+ rows, 2013 → today, family-consolidated✅
Insider trades (Forms 3/4/5)11M+ transactions, open-market classified✅
Congress tradingSTOCK Act disclosures, both chambers✅
Crypto ETF exposureInstitutional spot-BTC-ETF holdings from 13F✅
Form 144Planned insider sales (forward-looking)✅
Fails-to-deliver + Reg SHOShort-side stress footprints✅
Stock prices & financialsDaily OHLCV + XBRL-derived 10-K/10-Q statements incl. cash, capex, free cash flow, buybacks, dividends✅
SEC filings gatewayAny filing document, signed shareable linkslist/index ✅ · documents Pro
Macro (Treasury, Fed, CPI, OFR stress)Daily federal sourcesPro
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 accessko.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
SetupPython env + installone command, zero install

Plans

Demo (no key)FreeProBuilder
Calls/daylimited20020,000200,000
Rows/request5005005,00050,000
Core SEC data✅✅✅✅
History depthlatestlatestfullfull
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

Source: README.md at commit 60f3423

Tools

32

get_institution_holdings

Get current stock holdings of an institutional investor (hedge fund, mutual fund, pension fund) from their latest SEC 13F filing. Returns top positions with share counts, values, and quarter-over-quarter changes. Every answer states its grain: ENTITY (a CIK that belongs to a manager family is answered for the whole family by default -- pass entity='filer' for that one filer's own 13F) and SECURITY (the default portfolio merges an issuer's share classes into one row, e.g. GOOG+GOOGL, and lists the per-class breakdown; pass `ticker` to get only that security). Shares and value are the 13F-reported totals over all legs; option legs are flagged. structuredContent carries exact shares/values and the grain fields.

Parameterspagelimitentitytickerinstitutionrequired

list_institutions

List top institutional investors (hedge funds, mutual funds, etc.) tracked in the SEC 13F database. Supports search by name and pagination.

Parameterspagelimitsearch

get_stock_profile

Get a company's profile — sector, market cap, price, P/E ratio, 52-week range, beta, dividend yield, and other key financials.

Parameterstickerrequired

get_stock_holders

Get top institutional holders of a stock from SEC 13F filings. Shows which hedge funds, mutual funds, and pension funds own the most shares, with quarter-over-quarter changes.

Parameterspagelimittickerrequired

get_stock_activity

Get institutional buying/selling activity trend for a stock over multiple quarters. Shows how many institutions are buying vs selling, net share changes, and value flows — useful for detecting accumulation or distribution patterns. Plan limits: Free/keyless access covers the latest 13F quarter only; the multi-quarter trend requires Pro. Omit `quarters` to get the most your plan allows. structuredContent carries the exact net shares/values. Each quarter carries ko.io's comparability state (comparable / split_adjusted with its split factor / not_comparable / first_reported): a null share or value flow means UNKNOWN (withheld), never zero.

Parameterstickerrequiredquarters

get_stock_price

Get historical daily stock prices (OHLC). Returns a summary by default; set series=true to get the full daily price series (for backtesting / charting).

Parameterslimitperiodseriestickerrequired

get_insider_trades

Get insider (SEC Form 4) transactions for one company. Two grains, and the answer says which: (1) with `executive_cik` -> one row per Form 4 transaction line, with its SEC code (P open-market or private purchase, S open-market or private sale, M/X/C option or RSU exercise/conversion, A grant/award, F shares withheld for tax, G gift, ...), shares, price and value; (2) without it -> one row per insider per trade date that AGGREGATES all that day's lines, split into code P/S purchases/sales (open market or private) versus all acquisitions/dispositions (which also count vests, exercises and tax withholding), with both dollar totals and the line count; when ko.io reports them, the Lines cell and structuredContent also carry that day's SEC codes (e.g. '4 (F 1, M 2, S 1)'). Do not read an aggregate day's total disposed value as a sale decision; use the P/S columns, whose dollar totals cover priced lines only (unpriced lines are counted and flagged as partial). Keyless/Free access covers the trailing 92 days; `period` beyond 1Q requires Pro. structuredContent carries the exact share counts and dollar amounts.

Parameterspagelimitperiodtickerrequiredexecutive_cik

list_insider_traders

List executives/insiders who have recently traded their company stock. Filter by role (CEO only or all executives). Useful for finding notable insider buying/selling activity across the market.

Parameterspagerolelimitsearch

get_congress_trades

Search individual stock trades disclosed by U.S. Congress members (House and Senate) under the STOCK Act. Returns a markdown table of transactions: member name, chamber, ticker, buy/sell type, transaction date, disclosure date (the gap between the two reveals reporting delay), dollar amount range, and owner (self/spouse/joint). Use for questions like 'What did Nancy Pelosi trade recently?', 'Which members bought NVDA?', or 'Show the largest Senate trades this quarter'. Filter by chamber, ticker, or member name; sort by traded value, trade count, or recency. For one member's profile and complete trading history, use get_congress_member instead.

Parameterspagesortlimitsearchtickerchamber

get_congress_member

Get detailed trading history of a specific U.S. Congress member. Shows individual trades with transaction types, amounts, and disclosure dates.

Parameterspagelimitmemberrequired

get_form144_notices

Get SEC Form 144 filings — notices of proposed sale of restricted/controlled securities by insiders. Filed before selling, these signal upcoming insider sales. Complements Form 4 (post-trade) with pre-trade intent.

Parameterslimittickerinsider_cik

sec_list_filings

List an entity's SEC filings from EDGAR (most recent first), each with its accession number. Provide the company's CIK (use search or get_stock_profile to find it). Returns accession numbers to pass to sec_get_filing_index / sec_get_filing_document.

Parameterstocikrequiredfromlimitform_type

sec_get_filing_index

Enumerate every file in a single SEC filing (primary document, exhibits, images, XBRL, the full .txt submission). Pass a file name from here to sec_get_filing_document.

Parameterscikrequiredaccession_norequired

sec_get_filing_document

Get a source document from a SEC filing, served by ko.io. Returns a ko.io LINK to the rendered document (open in a browser) plus, optionally, an extracted text excerpt. Never returns the whole file — for full content, open the link or request a specific section. Requires a paid ko.io plan (Pro): on Free or keyless access the call returns an explicit plan-limit error. Use sec_list_filings / sec_get_filing_index (open on every plan) to find filings and their files.

Parameterscikrequiredfileaccession_norequiredinclude_excerpt

get_stock_financials

Get quarterly or annual financial statements for a company (revenue, net income, EPS, margins, cash flow, debt ratios) from SEC 10-K/10-Q filings. Plan limits: the Free plan and keyless access return only the latest quarterly statement; annual statements and earlier quarters require Pro (a request for them returns an explicit plan-limit error, never 'no data'). structuredContent carries the exact reported values.

Parameterslimittickerrequiredperiod_type

get_treasury_yields

Get U.S. Treasury yield curve data — daily yields for maturities from 1-month to 30-year. Essential for understanding interest rate environment and yield curve shape.

Parametersdays

get_fed_rates

Get daily U.S. policy and money-market interest rates as a markdown table: Effective Fed Funds Rate, SOFR, Prime Rate, and benchmark Treasury yields (3M, 2Y, 10Y, 30Y) per date, newest first. Use for monetary-policy questions like 'Where is the Fed funds rate now?' or 'How has SOFR moved this quarter?', or to compare policy rates against long-end yields for inversion analysis. Covers up to 10 years of daily history. For the full Treasury curve across all maturities, use get_treasury_yields instead.

Parametersdays

get_economic_indicators

Get U.S. economic indicators from BLS — CPI (inflation), PPI (producer prices), Non-farm Payrolls (employment), Unemployment Rate, JOLTS. Filter by category.

Parametersdayspagelimitcategory

get_ftd_data

Get SEC fails-to-deliver (FTD) data for a stock. Each quantity is the aggregate net BALANCE of shares that had failed to deliver and were still outstanding on that settlement date, as published by the SEC -- NOT the number of new fails that day. Balances carry over between days, so never sum quantities across dates (that counts the same unsettled shares repeatedly); compare levels or take the maximum instead. Fails arise from many causes (operational and processing delays, long sales, market-maker activity), and FTD data on its own is not evidence of naked short selling. Free/keyless access covers the trailing 92 days. structuredContent carries the exact share quantities.

Parametersdayspagelimittickerrequired

get_financial_stress

Get the OFR Financial Stress Index — a daily indicator of stress in global financial markets. Values above 0 indicate above-average stress.

Parametersdayspagelimit

get_crypto_exposure

Get a market-wide summary of institutional exposure to US spot crypto ETFs (Bitcoin ETF complex: IBIT, FBTC, GBTC, etc.) from the latest quarter of SEC 13F filings. Returns total institutional USD held, quarter-over-quarter change, and a per-ETF breakdown (holders, USD, QoQ).

Takes no parameters.

get_crypto_holders

List institutional investors holding US spot crypto ETFs (Bitcoin ETF complex), ranked by total USD held, from the latest quarter of SEC 13F filings. Optionally filter to holders of a specific ETF via the `product` parameter (e.g. 'IBIT').

Parameterspagelimitproduct

get_crypto_holder

Get one institution's spot crypto-ETF holdings (Bitcoin ETF complex): its per-ETF positions in the latest filed quarter (shares, USD, QoQ change, action) plus its rank among all crypto-ETF holders. Use a CIK number (find it with get_crypto_holders or the search tool).

Parametersinstitutionrequired

get_eu_markets

Which European markets and datasets ko.io serves: for Sweden, Netherlands, Denmark and the UK, the status of insider dealings (PDMR), major holdings, net short positions and annual reports -- live (with latest source date), pending (not activated yet) or not offered. Call first when unsure whether an EU dataset is live.

Takes no parameters.

get_eu_insider_dealings

European insider dealings: transactions by managers and closely associated persons (PDMR, MAR article 19) from the national registers of Sweden, Netherlands, Denmark or the UK, newest first. One row per notice transaction line with person, role, nature, quantity, price and per-row source credit. Filter by issuer id; check get_eu_markets for which markets are live.

Parameterspagelimitissuercountryrequired

get_eu_major_holdings

European major holdings (voting-rights) notifications for Sweden, Netherlands, Denmark or the UK, newest first: issuer, holder(s), voting-rights % after (incl. instruments), shares %, reason, per-row source credit. Filter by issuer id; check get_eu_markets for which markets are live.

Parameterspagelimitissuercountryrequired

get_eu_short_positions

European disclosed net short positions for Sweden, Netherlands or Denmark (not offered for the UK), newest position date first: holder, issuer, ISIN, net short % of issued capital, per-row source credit. Filter by issuer id; check get_eu_markets for which markets are live.

Parameterspagelimitissuercountryrequired

get_eu_annual_reports

European annual financial report filings for Sweden, Netherlands, Denmark or the UK, newest first: issuer, LEI, period end, link to the original report where the source allows, per-row source credit. Filter by issuer id; check get_eu_markets for which markets are live.

Parameterspagelimitissuercountryrequired

get_eu_issuer

One European issuer in one market (se, nl, dk, uk): identity (name, LEI, ISIN, venue) and its newest rows of insider dealings, major holdings, net short positions and annual reports, each with source credit. Takes the issuer id from any get_eu_* row (issuer.id).

Parametersissuerrequiredcountryrequired

get_gov_contracts

U.S. federal prime-contract obligations (USAspending, FY2015+) attributed to one issuer, across all share classes. Gross, signed deobligations, net, monthly series and agencies. include=actions adds actions; award_id returns only attributed actions on that award plus award context. Exact decimal strings. Recent months are provisional; Defense reports about 90 days late. Automatic exact matches cover companies listed today, plus reviewed links. No link does not mean no contracts. Free: trailing 92 days; history: Pro.

Parameterstofrompagesortlimitagencyperiodtickerrequiredincludeaward_idsub_agencyfiscal_year

search_gov_contracts

Search U.S. federal prime-contract actions (USAspending, FY2015+) across companies, or rank companies by obligations with view=companies. Companies listed today plus reviewed links. Filter by ticker(s), agency, sub-agency, fiscal year or dates. Actions also support recipient, NAICS, award type and minimum absolute amount. Without tickers the window is at most 366 days. Exact decimal strings; signed obligations, not payments. Provisional recent months; Defense reports about 90 days late. Free: trailing 92 days; history: Pro.

Parameterstofrompageviewlimitnaicsagencyperiodtickerrecipientaward_typemin_amount+4 more

Version history

1
  1. v1.0.0LatestSep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts