Ko MCP

Official24 toolsLive

by SharpLu · TypeScript

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

Topics

13fai-agentsfinancial-datafintechinsider-tradingllm-toolsmcpmodel-context-protocolsdksec-edgar

Captured live from the server via tools/list.

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.

Parameters3

institution	string	required	Institution CIK number (e.g. '1067983'), slug (e.g. 'berkshire-hathaway'), or name (e.g. 'Berkshire Hathaway') — names are resolved automatically.
page	integer	optional	Page number
limit	integer	optional	Results per page

Raw schema

{
  "type": "object",
  "properties": {
    "institution": {
      "type": "string",
      "maxLength": 200,
      "description": "Institution CIK number (e.g. '1067983'), slug (e.g. 'berkshire-hathaway'), or name (e.g. 'Berkshire Hathaway') — names are resolved automatically."
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "default": 1,
      "description": "Page number"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 50,
      "description": "Results per page"
    }
  },
  "required": [
    "institution"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_institutions

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

Parameters3

search	string	optional	Search by institution or founder name
page	integer	optional	Page number
limit	integer	optional	Results per page

Raw schema

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "maxLength": 200,
      "description": "Search by institution or founder name"
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "default": 1,
      "description": "Page number"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20,
      "description": "Results per page"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

ticker

string

required

Stock ticker symbol (e.g. 'AAPL', 'NVDA', 'MSFT')

Raw schema

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "maxLength": 200,
      "description": "Stock ticker symbol (e.g. 'AAPL', 'NVDA', 'MSFT')"
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters3

ticker	string	required	Stock ticker symbol (e.g. 'NVDA')
page	integer	optional	Page number
limit	integer	optional	Results per page

Raw schema

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "maxLength": 200,
      "description": "Stock ticker symbol (e.g. 'NVDA')"
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "default": 1,
      "description": "Page number"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20,
      "description": "Results per page"
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters2

ticker	string	required	Stock ticker symbol
quarters	integer	optional	Number of quarters to return (default 8 = 2 years)

Raw schema

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "maxLength": 200,
      "description": "Stock ticker symbol"
    },
    "quarters": {
      "type": "integer",
      "minimum": 1,
      "maximum": 40,
      "default": 8,
      "description": "Number of quarters to return (default 8 = 2 years)"
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

Parameters4

ticker	string	required	Stock ticker symbol
period	string	optional	Look-back window
series	boolean	optional	If true, return the full daily OHLC series (up to `limit` rows) instead of just a summary.
limit	integer	optional	Max rows of the daily series to return when series=true.

Raw schema

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "maxLength": 200,
      "description": "Stock ticker symbol"
    },
    "period": {
      "type": "string",
      "enum": [
        "1y",
        "3y",
        "5y",
        "10y"
      ],
      "default": "1y",
      "description": "Look-back window"
    },
    "series": {
      "type": "boolean",
      "default": false,
      "description": "If true, return the full daily OHLC series (up to `limit` rows) instead of just a summary."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3000,
      "default": 500,
      "description": "Max rows of the daily series to return when series=true."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_insider_trades

Get insider/executive stock trades (SEC Form 4) for a company. Shows CEO, CFO, directors, and other officers buying or selling their own company's stock — a key signal for institutional investors.

Parameters3

ticker	string	required	Stock ticker symbol (e.g. 'AAPL')
executive_cik	string	optional	Filter by specific executive CIK (from list_insider_traders)
limit	integer	optional	Max trades to return

Raw schema

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "maxLength": 200,
      "description": "Stock ticker symbol (e.g. 'AAPL')"
    },
    "executive_cik": {
      "type": "string",
      "description": "Filter by specific executive CIK (from list_insider_traders)"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 50,
      "description": "Max trades to return"
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters4

search	string	optional	Search by name or ticker
role	string	optional	Filter by role (case-insensitive): CEO, executive/officer, or all
page	integer	optional
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "maxLength": 200,
      "description": "Search by name or ticker"
    },
    "role": {
      "type": "string",
      "enum": [
        "ceo",
        "executive",
        "all"
      ],
      "default": "all",
      "description": "Filter by role (case-insensitive): CEO, executive/officer, or all"
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "default": 1
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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, party, state, 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.

Parameters8

chamber	string	optional	Congressional chamber: house, senate, or all (default all)
party	string	optional	Filter by party — D=Democrat, R=Republican, I=Independent
ticker	string	optional	Stock ticker symbol to filter by, e.g. NVDA or AAPL
state	string	optional	Member 2-letter U.S. state code, e.g. CA or TX
search	string	optional	Full or partial member name, e.g. 'Pelosi' or 'Dan Crenshaw'
sort	string	optional	Sort order — volume (most traded value), trades (most trades), recent (latest first)
page	integer	optional	Page number for pagination (default 1)
limit	integer	optional	Trades per page, 1-50 (default 20)

Raw schema

{
  "type": "object",
  "properties": {
    "chamber": {
      "type": "string",
      "enum": [
        "house",
        "senate",
        "all"
      ],
      "default": "all",
      "description": "Congressional chamber: house, senate, or all (default all)"
    },
    "party": {
      "type": "string",
      "enum": [
        "D",
        "R",
        "I",
        "all"
      ],
      "default": "all",
      "description": "Filter by party — D=Democrat, R=Republican, I=Independent"
    },
    "ticker": {
      "type": "string",
      "maxLength": 200,
      "description": "Stock ticker symbol to filter by, e.g. NVDA or AAPL"
    },
    "state": {
      "type": "string",
      "maxLength": 200,
      "description": "Member 2-letter U.S. state code, e.g. CA or TX"
    },
    "search": {
      "type": "string",
      "maxLength": 200,
      "description": "Full or partial member name, e.g. 'Pelosi' or 'Dan Crenshaw'"
    },
    "sort": {
      "type": "string",
      "enum": [
        "volume",
        "trades",
        "recent"
      ],
      "default": "volume",
      "description": "Sort order — volume (most traded value), trades (most trades), recent (latest first)"
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "default": 1,
      "description": "Page number for pagination (default 1)"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20,
      "description": "Trades per page, 1-50 (default 20)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_congress_member

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

Parameters3

member	string	required	Member slug (e.g. 'nancy-pelosi', 'dan-crenshaw'). Use get_congress_trades or search to find exact slugs.
page	integer	optional
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "member": {
      "type": "string",
      "description": "Member slug (e.g. 'nancy-pelosi', 'dan-crenshaw'). Use get_congress_trades or search to find exact slugs."
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "default": 1
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 50
    }
  },
  "required": [
    "member"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search

Search across institutions, stocks, and insider traders in the ko.io SEC database. Use this first when you have a name but need the CIK number, ticker, or slug to use with other tools.

Parameters2

query	string	required	Search query — company name, ticker, person name, or institution name (min 2 characters)
limit	integer	optional	Max results per category

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 2,
      "maxLength": 200,
      "description": "Search query — company name, ticker, person name, or institution name (min 2 characters)"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "default": 5,
      "description": "Max results per category"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters3

ticker	string	optional	Filter by stock ticker (e.g. 'AAPL')
insider_cik	string	optional	Filter by insider's CIK number
limit	integer	optional	Max notices to return

Raw schema

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "maxLength": 200,
      "description": "Filter by stock ticker (e.g. 'AAPL')"
    },
    "insider_cik": {
      "type": "string",
      "maxLength": 200,
      "description": "Filter by insider's CIK number"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 50,
      "description": "Max notices to return"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters5

cik	string	required	Company CIK number (e.g. '320193' for Apple)
form_type	string	optional	Exact SEC form filter, e.g. '10-K', '13F-HR', '8-K'
from	string	optional	Earliest filing date, ISO YYYY-MM-DD
to	string	optional	Latest filing date, ISO YYYY-MM-DD
limit	integer	optional	Max filings to return

Raw schema

{
  "type": "object",
  "properties": {
    "cik": {
      "type": "string",
      "maxLength": 200,
      "description": "Company CIK number (e.g. '320193' for Apple)"
    },
    "form_type": {
      "type": "string",
      "maxLength": 200,
      "description": "Exact SEC form filter, e.g. '10-K', '13F-HR', '8-K'"
    },
    "from": {
      "type": "string",
      "maxLength": 200,
      "description": "Earliest filing date, ISO YYYY-MM-DD"
    },
    "to": {
      "type": "string",
      "maxLength": 200,
      "description": "Latest filing date, ISO YYYY-MM-DD"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 50,
      "description": "Max filings to return"
    }
  },
  "required": [
    "cik"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters2

cik	string	required	Company CIK number
accession_no	string	required	Accession number, e.g. '0000320193-23-000106'

Raw schema

{
  "type": "object",
  "properties": {
    "cik": {
      "type": "string",
      "maxLength": 200,
      "description": "Company CIK number"
    },
    "accession_no": {
      "type": "string",
      "maxLength": 200,
      "description": "Accession number, e.g. '0000320193-23-000106'"
    }
  },
  "required": [
    "cik",
    "accession_no"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters4

cik	string	required	Company CIK number
accession_no	string	required	Accession number, e.g. '0000320193-23-000106'
file	string	optional	File name within the filing (from sec_get_filing_index). Omit for the primary document.
include_excerpt	boolean	optional	Include a text excerpt (first ~6000 chars) in the response

Raw schema

{
  "type": "object",
  "properties": {
    "cik": {
      "type": "string",
      "maxLength": 200,
      "description": "Company CIK number"
    },
    "accession_no": {
      "type": "string",
      "maxLength": 200,
      "description": "Accession number, e.g. '0000320193-23-000106'"
    },
    "file": {
      "type": "string",
      "maxLength": 200,
      "description": "File name within the filing (from sec_get_filing_index). Omit for the primary document."
    },
    "include_excerpt": {
      "type": "boolean",
      "default": true,
      "description": "Include a text excerpt (first ~6000 chars) in the response"
    }
  },
  "required": [
    "cik",
    "accession_no"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters3

ticker	string	required	Stock ticker symbol (e.g. 'AAPL', 'MSFT')
period_type	string	optional	Period type — quarterly (10-Q) or annual (10-K)
limit	integer	optional	Number of periods to return (default 8)

Raw schema

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "maxLength": 200,
      "description": "Stock ticker symbol (e.g. 'AAPL', 'MSFT')"
    },
    "period_type": {
      "type": "string",
      "enum": [
        "quarterly",
        "annual"
      ],
      "default": "quarterly",
      "description": "Period type — quarterly (10-Q) or annual (10-K)"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "default": 8,
      "description": "Number of periods to return (default 8)"
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

days

integer

optional

Days of daily history to return, 1-3650 (default 30 = last month)

Raw schema

{
  "type": "object",
  "properties": {
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3650,
      "default": 30,
      "description": "Days of daily history to return, 1-3650 (default 30 = last month)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

days

integer

optional

Number of days of history (default 30)

Raw schema

{
  "type": "object",
  "properties": {
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3650,
      "default": 30,
      "description": "Number of days of history (default 30)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters2

category	string	optional	Category (case-insensitive): cpi/inflation, ppi, nfp/payrolls, unemployment, jolts, or all
days	integer	optional	Number of days of history (default 365)

Raw schema

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "cpi",
        "unemployment",
        "nfp",
        "ppi",
        "jolts",
        "all"
      ],
      "default": "all",
      "description": "Category (case-insensitive): cpi/inflation, ppi, nfp/payrolls, unemployment, jolts, or all"
    },
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3650,
      "default": 365,
      "description": "Number of days of history (default 365)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_ftd_data

Get SEC Failures-to-Deliver (FTD) data for a stock. High FTD quantities may indicate naked short selling or settlement issues.

Parameters2

ticker	string	required	Stock ticker symbol (e.g. 'GME', 'TSLA')
days	integer	optional	Number of days of history (default 90)

Raw schema

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "maxLength": 200,
      "description": "Stock ticker symbol (e.g. 'GME', 'TSLA')"
    },
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1825,
      "default": 90,
      "description": "Number of days of history (default 90)"
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

days

integer

optional

Number of days of history (default 365)

Raw schema

{
  "type": "object",
  "properties": {
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3650,
      "default": 365,
      "description": "Number of days of history (default 365)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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').

Parameters3

product	string	optional	Filter to holders of a specific spot crypto ETF ticker, e.g. 'IBIT', 'FBTC', 'GBTC'.
page	integer	optional	Page number
limit	integer	optional	Results per page

Raw schema

{
  "type": "object",
  "properties": {
    "product": {
      "type": "string",
      "maxLength": 200,
      "description": "Filter to holders of a specific spot crypto ETF ticker, e.g. 'IBIT', 'FBTC', 'GBTC'."
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "default": 1,
      "description": "Page number"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 50,
      "description": "Results per page"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

Parameters1

institution

string

required

Institution CIK number (e.g. '1512857' for Brevan Howard) or name (e.g. 'BlackRock').

Raw schema

{
  "type": "object",
  "properties": {
    "institution": {
      "type": "string",
      "maxLength": 200,
      "description": "Institution CIK number (e.g. '1512857' for Brevan Howard) or name (e.g. 'BlackRock')."
    }
  },
  "required": [
    "institution"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md7 KBView on GitHub

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 quota
for h in ko.stocks.holders("NVDA"):
    print(h["name"], h["holding_value"], h["action"])

In TypeScript:

bash

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

Directory	What it is
`server/`	The hosted MCP server (mcp.ko.io) — Cloudflare Worker, 24 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 deploys it. You can also self-host it on your own Cloudflare account (cd server && 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, 26 pipelines refreshing on each source's publication schedule).

Note: ko-edgar is live on PyPI (pip install ko-edgar). The npm packages @ko-io/sdk and @ko-io/mcp-sec-data publish shortly. 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	85M+ 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 statements	✅
SEC filings gateway	Any filing document, signed shareable links	list/index ✅ · documents Pro
Macro (Treasury, Fed, CPI, OFR stress)	Daily federal sources	Pro

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 24 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 · 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

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

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 $29/mo	Team $99/mo
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. Details →

Contributing

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

MIT © ko.io

Install

Tools (24)

get_institution_holdingslist_institutionsget_stock_profileget_stock_holdersget_stock_activityget_stock_priceget_insider_tradeslist_insider_traders

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://mcp.ko.io/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "ko-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.ko.io/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.