form4api-mcp

# form4api-mcp

> 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** — 38 tools + 6 ready-made research prompts

[![npm version](https://badge.fury.io/js/form4api-mcp.svg)](https://www.npmjs.com/package/form4api-mcp)
[![Available on mcp.so](https://img.shields.io/badge/mcp.so-form4api-blue)](https://mcp.so)
[![form4api-mcp MCP server](https://glama.ai/mcp/servers/theodor90/form4api-mcp/badges/score.svg)](https://glama.ai/mcp/servers/theodor90/form4api-mcp)

An [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.

**Four data-quality claims no scraping-based alternative can make:**

- 🛡 **Amendment-aware** — Form 4/A amendments are reconciled automatically. No double-counting when an insider corrects a filing.
- 🎯 **10b5-1 clean** — every transaction flagged as pre-scheduled (10b5-1 plan) or discretionary. Cluster signals exclude planned trades by construction.
- 📜 **Form 144 intent-to-sell** — 118K+ Form 144 filings indexed. Catch insider sales ~2 days before they hit Form 4.
- 🏛 **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.

---

## Quick install

### 1. Get a free API key

Go to [www.form4api.com](https://www.form4api.com) → Sign in → Dashboard. Free plan includes 500 requests/day, no credit card required.

### 2. Add to your MCP client

**Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "form4api": {
      "command": "npx",
      "args": ["-y", "form4api-mcp"],
      "env": {
        "FORM4API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

Restart the client. The tools appear automatically.

**Claude Code (CLI):**
```sh
claude mcp add form4api -- npx -y form4api-mcp
```
…then set `FORM4API_KEY` in your shell or in `~/.claude/mcp.json`.

**Cursor** — edit `~/.cursor/mcp.json` (user-level) or `.cursor/mcp.json` (workspace-level):

```json
{
  "mcpServers": {
    "form4api": {
      "command": "npx",
      "args": ["-y", "form4api-mcp"],
      "env": {
        "FORM4API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

Restart Cursor. The tools appear automatically.

**Windsurf** — edit `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "form4api": {
      "command": "npx",
      "args": ["-y", "form4api-mcp"],
      "env": {
        "FORM4API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

Restart Windsurf. The tools appear automatically.

**VS Code** — edit `.vscode/mcp.json` (workspace-level). Note: VS Code uses the `servers` key (not `mcpServers`):

```json
{
  "servers": {
    "form4api": {
      "command": "npx",
      "args": ["-y", "form4api-mcp"],
      "env": {
        "FORM4API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

Restart VS Code. The tools appear automatically.

**Codex CLI** — config is TOML at `~/.codex/config.toml`:

```toml
[mcp_servers.form4api]
command = "npx"
args = ["-y", "form4api-mcp"]
env = { FORM4API_KEY = "YOUR_API_KEY" }
```

### Verify it works

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

Example: *"Run the verify_setup tool to confirm the MCP is configured correctly."*

### Try before you commit a key

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

```bash
FORM4API_KEY="" npx form4api-mcp
```

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

### 3. Or run directly

```bash
FORM4API_KEY=YOUR_API_KEY npx form4api-mcp
```

---

## Available tools (38)

### Search

| Tool | Description | Plan |
|---|---|---|
| `search` | Resolve a company name, ticker fragment, or a person's name to a ticker or CIK — the usual first call when you don't already have an identifier. Returns separately-ranked `companies` and `insiders` lists | Free |

### Form 4 insider trading

| Tool | Description | Plan |
|---|---|---|
| `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) |
| `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 |
| `get_recent_filings` | Most recent Form 4 filings, optionally filtered by ticker | Free |
| `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 |
| `get_filing` | Single filing by accession number | Free |
| `get_insider_profile` | Insider profile — name, title, director/officer/10pct owner flags | Free |
| `get_insider_transactions` | All transactions for a specific insider (by CIK) | Free |
| `get_company_overview` | Company profile — name, CIK, SIC sector, state, website, filing counts | Free |
| `get_company_insiders` | All insiders who have filed Form 4s for a company | Free |
| `list_companies` | List companies, sorted by name or filing count | Free |
| `get_insider_directory` | Browse insiders alphabetically by surname — an A-Z rail with a count per letter, plus one page of insiders under the requested letter | Free |
| `get_insider_career_summary` | Aggregate career rollup: total bought/sold, top companies, 10b5-1 split, return averages | Pro |
| `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 |
| `get_insider_leaderboard` | Top insiders ranked by `hit_rate` or `avg_return`; filter by `horizon` (3m/6m), `min_trades`, and `limit` | Business |

### Signals + sentiment

| Tool | Description | Plan |
|---|---|---|
| `get_signals` | Cluster buy/sell signals — multiple insiders at the same company in the same direction. **Excludes 10b5-1 trades automatically** | Business |
| `get_sentiment` | MSPR-style monthly sentiment score per ticker (-100 to +100). **10b5-1 excluded** so the score reflects real insider conviction | Business |

### Form 144 + institutional

| Tool | Description | Plan |
|---|---|---|
| `get_form144` | Notice-of-proposed-sale filings — early signal ~2 days before Form 4 sale lands | Business |
| `get_holdings` | Institutional positions from Form 13F-HR (filter by ticker, CUSIP, manager, quarter, min value) | Business |
| `get_managers` | Institutional manager index with latest AUM | Business |
| `explain_signal` | Explain why a signal fired — the insiders and trades counted, exclusions, and criteria | Business |
| `get_data_quality` | Public data-quality, freshness and coverage metrics | Free |
| `list_schedule13_dg` | Schedule 13D/13G >5% beneficial-ownership crossings for a company — filer, ownership percent, event date, form type | Business |

### Congress + convergence

| Tool | Description | Plan |
|---|---|---|
| `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) |
| `list_congress_politicians` | Ranked rollup of politicians by congressional trade activity — total/buy/sell counts, most recent disclosure | Pro |
| `get_congress_politician` | One politician's full profile by bioguide ID — totals, top traded tickers, most recent trades | Pro |
| `get_congress_ticker_rollup` | Which politicians traded a given ticker, with net buy/sell counts | Pro |
| `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 |

### Utility

| Tool | Description | Plan |
|---|---|---|
| `check_usage` | Your API key usage stats and current plan | Free |