{
  "markdown": "# form4api-mcp\n\n> Production-grade SEC Form 4 insider trading data for any MCP-compatible AI assistant — **amendment-aware, 10b5-1 clean, with Form 144 + institutional 13F-HR overlay, plus congressional STOCK Act trades and insider/Congress convergence** — 35 tools + 6 ready-made research prompts\n\n[![npm version](https://badge.fury.io/js/form4api-mcp.svg)](https://www.npmjs.com/package/form4api-mcp)\n[![Available on mcp.so](https://img.shields.io/badge/mcp.so-form4api-blue)](https://mcp.so)\n[![form4api-mcp MCP server](https://glama.ai/mcp/servers/theodor90/form4api-mcp/badges/score.svg)](https://glama.ai/mcp/servers/theodor90/form4api-mcp)\n\nAn [MCP](https://modelcontextprotocol.io) server that exposes the hosted [Form4API](https://www.form4api.com) REST API to Claude Desktop, Cursor, Windsurf, VS Code, Codex CLI, and any other MCP-compatible client. Configured once, your LLM can answer questions about insider trading, institutional positioning, and intent-to-sell filings directly during research sessions.\n\n**Four data-quality claims no scraping-based alternative can make:**\n\n- 🛡 **Amendment-aware** — Form 4/A amendments are reconciled automatically. No double-counting when an insider corrects a filing.\n- 🎯 **10b5-1 clean** — every transaction flagged as pre-scheduled (10b5-1 plan) or discretionary. Cluster signals exclude planned trades by construction.\n- 📜 **Form 144 intent-to-sell** — 118K+ Form 144 filings indexed. Catch insider sales ~2 days before they hit Form 4.\n- 🏛 **Institutional × insider join** — every transaction carries the current 13F-HR ownership context (top-3 holders, AUM trend) in the same response: no second call, no client-side join. Among the self-serve SEC data APIs we've surveyed, none return both sides in one query — sec-api.io and Kaleidoscope both ship 13F and insider data as separate endpoints.\n\n---\n\n## Quick install\n\n### 1. Get a free API key\n\nGo to [www.form4api.com](https://www.form4api.com) → Sign in → Dashboard. Free plan includes 500 requests/day, no credit card required.\n\n### 2. Add to your MCP client\n\n**Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"form4api\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"form4api-mcp\"],\n      \"env\": {\n        \"FORM4API_KEY\": \"YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\nRestart the client. The tools appear automatically.\n\n**Claude Code (CLI):**\n```sh\nclaude mcp add form4api -- npx -y form4api-mcp\n```\n…then set `FORM4API_KEY` in your shell or in `~/.claude/mcp.json`.\n\n**Cursor** — edit `~/.cursor/mcp.json` (user-level) or `.cursor/mcp.json` (workspace-level):\n\n```json\n{\n  \"mcpServers\": {\n    \"form4api\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"form4api-mcp\"],\n      \"env\": {\n        \"FORM4API_KEY\": \"YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\nRestart Cursor. The tools appear automatically.\n\n**Windsurf** — edit `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"form4api\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"form4api-mcp\"],\n      \"env\": {\n        \"FORM4API_KEY\": \"YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\nRestart Windsurf. The tools appear automatically.\n\n**VS Code** — edit `.vscode/mcp.json` (workspace-level). Note: VS Code uses the `servers` key (not `mcpServers`):\n\n```json\n{\n  \"servers\": {\n    \"form4api\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"form4api-mcp\"],\n      \"env\": {\n        \"FORM4API_KEY\": \"YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\nRestart VS Code. The tools appear automatically.\n\n**Codex CLI** — config is TOML at `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.form4api]\ncommand = \"npx\"\nargs = [\"-y\", \"form4api-mcp\"]\nenv = { FORM4API_KEY = \"YOUR_API_KEY\" }\n```\n\n### Verify it works\n\nAsk your LLM to run the `verify_setup` tool — it confirms your API key is valid and the MCP server is reachable, or returns the exact fix steps.\n\nExample: *\"Run the verify_setup tool to confirm the MCP is configured correctly.\"*\n\n### Try before you commit a key\n\n`get_public_stats` is a **keyless tool** — it works with no `FORM4API_KEY` set. Try it first to preview live data coverage before signing up:\n\n```bash\nFORM4API_KEY=\"\" npx form4api-mcp\n```\n\nOnce you like what you see, sign up for a free key at [www.form4api.com](https://www.form4api.com) → set `FORM4API_KEY` → all tools unlock.\n\n### 3. Or run directly\n\n```bash\nFORM4API_KEY=YOUR_API_KEY npx form4api-mcp\n```\n\n---\n\n## Available tools (35)\n\n### Form 4 insider trading\n\n| Tool | Description | Plan |\n|---|---|---|\n| `research_company` | Bundled insider-research context for one ticker in a single call — company profile, recent transactions, cluster signals, sentiment, and a computed buy/sell direction summary. Replaces 4 separate calls and degrades gracefully when a section needs a higher plan | Free (signals/sentiment sections need Business) |\n| `get_transactions` | Search insider transactions — filter by ticker, insider, date range, transaction codes or whole categories (`exclude_category=derivatives`), 10b5-1 plan trades, a dollar floor (`min_value`), the 13F ownership trend (`inst_ownership_trend`), or use `significant=true` for real discretionary buys/sells only. Pro adds the remaining trade-size screens (`max_value`, `min_shares`, `max_shares`) and post-trade-return screening (`min_return_1d`…`max_return_6m`, `has_returns`; returns are fractions, 0.05 = +5%). Paging depth is plan-limited — see Plans | Free |\n| `get_recent_filings` | Most recent Form 4 filings, optionally filtered by ticker | Free |\n| `list_filings` | Form 4 filings as a paginated list, newest filed first — filter by ticker, cik, or a filed-date window. Use this to page through filings; `get_recent_filings` is the unfiltered head of the same feed | Free |\n| `get_filing` | Single filing by accession number | Free |\n| `get_insider_profile` | Insider profile — name, title, director/officer/10pct owner flags | Free |\n| `get_insider_transactions` | All transactions for a specific insider (by CIK) | Free |\n| `get_company_overview` | Company profile — name, CIK, SIC sector, state, website, filing counts | Free |\n| `get_company_insiders` | All insiders who have filed Form 4s for a company | Free |\n| `list_companies` | List companies, sorted by name or filing count | Free |\n| `get_insider_career_summary` | Aggregate career rollup: total bought/sold, top companies, 10b5-1 split, return averages | Pro |\n| `get_insider_scorecard` | Buy track-record scorecard for an insider (CIK) — hit rate and avg/median return on discretionary open-market buys; null when fewer than 5 matured samples | Pro |\n| `get_insider_leaderboard` | Top insiders ranked by `hit_rate` or `avg_return`; filter by `horizon` (3m/6m), `min_trades`, and `limit` | Business |\n\n### Signals + sentiment\n\n| Tool | Description | Plan |\n|---|---|---|\n| `get_signals` | Cluster buy/sell signals — multiple insiders at the same company in the same direction. **Excludes 10b5-1 trades automatically** | Business |\n| `get_sentiment` | MSPR-style monthly sentiment score per ticker (-100 to +100). **10b5-1 excluded** so the score reflects real insider conviction | Business |\n\n### Form 144 + institutional\n\n| Tool | Description | Plan |\n|---|---|---|\n| `get_form144` | Notice-of-proposed-sale filings — early signal ~2 days before Form 4 sale lands | Business |\n| `get_holdings` | Institutional positions from Form 13F-HR (filter by ticker, CUSIP, manager, quarter, min value) | Business |\n| `get_managers` | Institutional manager index with latest AUM | Business |\n| `explain_signal` | Explain why a signal fired — the insiders and trades counted, exclusions, and criteria | Business |\n| `get_data_quality` | Public data-quality, freshness and coverage metrics | Free |\n\n### Congress + convergence\n\n| Tool | Description | Plan |\n|---|---|---|\n| `list_congress_trades` | Congressional STOCK Act trades (periodic transaction reports) — filter by ticker, politician, party, chamber, state, transaction type, min amount, or date range. **Coverage is U.S. House only** — Senate eFD blocks datacenter traffic, so `chamber=Senate` matches nothing and the response carries `X-Coverage-Note: chamber-not-covered`. Every row carries `amountLow`/`amountHigh` (disclosed ranges, never a fabricated midpoint) and `disclosureLagDays` — up to 45 days under the STOCK Act, so \"real-time\" here means minutes-after-disclosure, not minutes-after-trade | Free (30-day disclosure window; Starter 366 days; Pro+ unlimited history) |\n| `list_congress_politicians` | Ranked rollup of politicians by congressional trade activity — total/buy/sell counts, most recent disclosure | Pro |\n| `get_congress_politician` | One politician's full profile by bioguide ID — totals, top traded tickers, most recent trades | Pro |\n| `get_congress_ticker_rollup` | Which politicians traded a given ticker, with net buy/sell counts | Pro |\n| `get_convergence_signals` | Tickers where an insider cluster-buy and a congressional purchase happened within a trailing window of each other. `strength` is documented arithmetic (distinct congressional purchasers × the signal's insider count) — never a black-box or predictive score. No performance/alpha claims are computed or implied | Pro |\n\n### Utility\n\n| Tool | Description | Plan |\n|---|---|---|\n| `check_usage` | Your API key usage stats and current plan | Free |\n| `get_key_activity` | Recent API requests for this key | Free |\n| `get_usage_history` | Daily request counts for the last N days | Free |\n| `search_insiders` | Substring search on insider names | Free |\n| `list_webhooks` | List your webhook subscriptions | Free |\n| `get_webhook_events` | Replay webhook delivery events since a timestamp | Free |\n| `verify_setup` | Verify the MCP is configured correctly — confirms API key is valid and server is reachable | Free |\n| `get_public_stats` | Public corpus-wide totals (filings, transactions, companies, 13F-HR AUM, ingestion latency) — no API key required | Free (keyless) |\n| `get_status_history` | Trailing 90-day daily uptime history for the public status page | Free (keyless) |\n| `health_ingestion` | Live ingestion-health check — Form 4 freshness, parse-queue backlog, price-feed staleness | Free (keyless) |\n\n---\n\n## Prompts (6)\n\nBeyond the 29 tools, this MCP ships 6 **prompts** — ready-made research recipes that a client can list (`prompts/list`) and load (`prompts/get`) so you don't have to hand-assemble the right tool sequence yourself. Each one tells the LLM exactly which SEC Form 4 / Form 144 / 13F-HR tools to call, in what order, and how to read plan-gated results.\n\n| Prompt | Args | What it does |\n|---|---|---|\n| `insider_monitor` | `ticker` | Recent SEC Form 4 insider activity for a ticker — transactions (10b5-1 flagged), cluster signals, sentiment — summarized as buy/sell conviction with post-trade-return context |\n| `cluster_buy_scan` | `days` (default 7) | Market-wide scan of recent cluster-buy signals, 10b5-1 excluded, ranked by conviction (insider count + $ value), each with a sentiment score |\n| `form144_early_warning` | `ticker` (optional) | Pending Form 144 notice-of-proposed-sale filings cross-referenced against recent Form 4 sells — flags discretionary (non-10b5-1) notices as the highest-signal early warnings, ~2 days ahead of the sale |\n| `exec_conviction_check` | `insider` (name or CIK) | An insider's career track record — total bought/sold, historical post-trade returns on discretionary buys, and whether their buying has historically beaten their scheduled 10b5-1 selling |\n| `institutional_insider_overlap` | `ticker` | Combines 13F-HR institutional holders with recent insider transactions to spot where smart money and insiders agree or diverge |\n| `post_selloff_buys` | `min_return` (default 0.05) | Screens insider buys with post-trade-return filters to surface historically-successful dip-buying patterns |\n\nThese map to the recipe workflows scraping-based Form 4 MCPs don't offer — each one leans on data this MCP alone exposes (10b5-1 flags, Form 144, 13F-HR join, per-insider return scoring). Plan requirements are honored honestly: prompts that touch Business-plan tools (`get_signals`, `get_sentiment`, `get_form144`, `get_holdings`, `get_managers`) or Pro-plan tools (`get_insider_career_summary`, `get_insider_scorecard`) instruct the LLM to surface the structured `upgrade_required` response rather than silently failing.\n\nIn Claude Desktop, prompts surface as a `/` slash-command picker; in Claude Code or other MCP clients, ask the assistant to \"use the insider_monitor prompt for NVDA\" (or similar) and it will fetch and follow the recipe.\n\n---\n\n## Example prompts\n\nConfigured? Ask your LLM:\n\n**Quality-led (these require our amendment-aware, 10b5-1 clean, joined dataset):**\n- *\"Show me cluster buy signals from this week — discretionary only, no planned trades\"*\n- *\"Which companies have insiders buying while institutional ownership is increasing this quarter?\"*\n- *\"Are there any Form 144 filings at NVDA suggesting upcoming sales?\"*\n- *\"What's the monthly insider sentiment for TSLA over the last 6 months, with 10b5-1 plans excluded?\"*\n- *\"Berkshire Hathaway's top 13F-HR holdings — what did they add or trim this quarter?\"*\n\n**Standard insider research:**\n- *\"What insider trades happened at NVDA in the last 30 days, excluding 10b5-1 plans?\"*\n- *\"What is Tim Cook's career insider-trading summary?\"*\n- *\"Show me all open-market purchases over $1M at Tesla in 2026\"*\n- *\"What has the CFO of Microsoft been doing with their shares this year?\"*\n\n---\n\n## Why this MCP vs scraping-based alternatives\n\nSome MCPs in this space scrape free public sites (e.g. openinsider.com) for Form 4 data. That's fine for a quick prototype but the data layer they give your LLM has structural gaps:\n\n| | form4api-mcp | Scraping-based MCPs |\n|---|---|---|\n| Form 4/A amendment handling | ✅ reconciled automatically | ❌ double-counts |\n| 10b5-1 plan flag | ✅ exposed on every transaction | ❌ planned + discretionary mixed |\n| Form 144 intent-to-sell | ✅ 118K+ filings | ❌ not exposed |\n| Institutional × insider join | ✅ top-3 holders + AUM trend per transaction | ❌ insider only |\n| Sentiment (10b5-1 excluded) | ✅ MSPR-style score | ❌ planned trades pollute score |\n| Source resilience | ✅ hosted API contract | ❌ breaks when source HTML changes |\n| Webhooks / production delivery | ✅ HMAC + retry + DLQ | ❌ MCP-only, no fallback |\n| SDKs | ✅ Python + JS | ❌ MCP-only |\n| Commercial support | ✅ | ❌ |\n\nIf your LLM session is the start of a real research workflow that eventually wants production delivery, picking the MCP that has a graduation path matters.\n\n---\n\n## Beyond MCP — when you need more\n\nThe MCP is the easiest entry point. When your workflow grows past LLM-mediated research, the rest of the Form4API platform is right behind it:\n\n- **[Webhooks](https://www.form4api.com/docs#webhooks)** — HMAC-signed, exponential backoff, dead-letter queue, auto-disable on persistent failure. For production pipelines, not just LLM chats.\n- **Python SDK** — `pip install form4api` ([PyPI](https://pypi.org/project/form4api/))\n- **JS / TypeScript SDK** — `npm install form4api` ([npm](https://www.npmjs.com/package/form4api))\n- **[Dashboard](https://www.form4api.com/dashboard)** — usage, billing self-serve, key rotation, webhook health, billing history.\n\nThe MCP wraps the same backend as all of the above — every fact your LLM cites can be re-fetched programmatically through any of these channels with the same key.\n\n---\n\n## Plans\n\n**22 of the 35 tools work on the free plan, and every tool that is free today stays free.**\nNew premium capability gets tiered as it ships; nothing that already works on your key is\ntaken away later.\n\n| Tool | Free | Pro | Business |\n|---|---|---|---|\n| `get_transactions`, `get_recent_filings`, `get_filing` | ✓ | ✓ | ✓ |\n| `get_insider_profile`, `get_insider_transactions` | ✓ | ✓ | ✓ |\n| `get_company_overview`, `get_company_insiders` | ✓ | ✓ | ✓ |\n| `get_insider_career_summary`, `get_insider_scorecard` | — | ✓ | ✓ |\n| `get_insider_leaderboard`, `get_signals`, `get_sentiment` | — | — | ✓ |\n| `get_form144`, `get_holdings`, `get_managers` | — | — | ✓ |\n| `list_congress_trades` | ✓ (30-day disclosure window) | ✓ (unlimited history) | ✓ (unlimited history) |\n| `list_congress_politicians`, `get_congress_politician`, `get_congress_ticker_rollup`, `get_convergence_signals` | — | ✓ | ✓ |\n| Requests/day | 500 | 50,000 | 250,000 |\n| `get_transactions` paging depth | 20 pages | unlimited | unlimited |\n\nFor a bulk historical pull, use the REST `/v1/transactions/export` endpoint (Business) rather\nthan paging — it streams the whole filtered set as CSV in one request.\n\n### What your agent sees at a paywall\n\nA gated call never surfaces a bare HTTP error. The MCP returns a structured\n`upgrade_required` payload so the model can explain the situation and the fix in one turn:\n\n```json\n{\n  \"error\": \"upgrade_required\",\n  \"required_plan\": \"business\",\n  \"current_plan\": \"Free\",\n  \"message\": \"This endpoint requires the Business plan or higher. Your current plan is Free.\",\n  \"unlocks\": \"Business ($149/mo) adds cluster-buy signals and sentiment scores, 13F institutional holdings and managers, Form 144 notices, bulk CSV export, and 250,000 requests/day.\",\n  \"upgrade_url\": \"https://www.form4api.com/dashboard/billing\",\n  \"pricing_url\": \"https://www.form4api.com/pricing\"\n}\n```\n\n`message` is the API's own explanation, kept verbatim — it names the specific limit or\nparameter that stopped the call, which is usually what the model needs to suggest a working\nalternative. The same shape is returned when a Pro-only *parameter* is used on an otherwise\nfree tool, so the model can simply retry without that filter.\n\nUpgrade at [form4api.com/dashboard/billing](https://www.form4api.com/dashboard/billing), or\ncompare tiers at [form4api.com/pricing](https://www.form4api.com/pricing).\n\n---\n\n## Data coverage\n\n- **1.3M+ Form 4 transactions** from SEC EDGAR\n- **596K+ filings** across all reporting companies\n- **118K+ Form 144** notice-of-proposed-sale filings (Business+)\n- **43M+ Form 13F-HR holdings** across 114K+ filings, $71T+ AUM in the latest complete quarter (Business+)\n- **3.3+ years of history** (since 2023-04)\n- **10b5-1 plan flag** on every transaction\n- **Amendment-aware** — Form 4/A reconciled\n- **Congressional STOCK Act trades** (Pro+) — House Clerk PTR + Senate eFD, digital filings, amounts always shown as disclosed ranges (`amountLow`/`amountHigh`), never a fabricated midpoint, plus `disclosureLagDays` on every trade (up to 45 days under the STOCK Act)\n- **Real-time ingestion** — new filings within minutes of SEC publication\n\n---\n\n## Install as a Claude Desktop Extension (DXT)\n\nA `manifest.json` is included at the repo root for one-click install via the [Desktop Extensions (DXT)](https://www.anthropic.com/news/desktop-extensions) format. Once Claude Desktop supports `.dxt` files natively, pack and install with:\n\n```bash\nnpx @anthropic-ai/dxt pack\n# Produces form4api-mcp.dxt — open it in Claude Desktop to install\n```\n\nUntil then, use the standard `claude_desktop_config.json` method described in Quick install above.\n\n---\n\n## How tools stay in sync with the backend\n\nThis MCP is split between two layers:\n\n- **Hand-written tools** in `src/tools/*.ts` (transactions, signals, sentiment, form144, holdings, …) — these carry the LLM-discriminator descriptions (amendment-aware, 10b5-1 clean, etc.) that make this MCP pick correctly over alternatives.\n- **Auto-generated tools** in `src/tools/_generated.ts` — produced from `https://api.form4api.com/openapi/v1.json` by `npm run codegen`. Every new backend endpoint that lands in the OpenAPI spec flows in here automatically. CI runs `npm run codegen:check` on every PR and fails the build if the committed file drifts from what the live spec would produce, so the MCP is never silently behind the backend.\n\nTo add a new generated tool: ship the endpoint on the backend, regenerate (`npm run codegen`), commit `src/tools/_generated.ts`, publish. No tool-wrapper code needed.\n\nThe 6 recipe **prompts** live in `src/prompts/recipes.ts` — also hand-written, not generated. They add no new backend surface area; each one is a client-side template that tells the LLM which existing tools to call and in what order.\n\n---\n\n## Links\n\n- [Form4API](https://www.form4api.com) — API homepage\n- [Documentation](https://www.form4api.com/docs) — Full REST API reference\n- [Dashboard](https://www.form4api.com/dashboard) — Manage your API key, view usage, configure webhooks\n- [Status](https://www.form4api.com/status) — live uptime, database, and ingestion-queue health\n- [npm](https://www.npmjs.com/package/form4api-mcp) — npm package\n- [mcp.so](https://mcp.so) — MCP server directory listing\n",
  "bytes": 20784,
  "sha": "80fc0ac10cb1fe596364b5765097dd5bf62459c5748a9801568a06a40329c862",
  "repo_slug": "theodor90/form4api-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_theodor90_form4api_mcp_0669f900/readme"
}