io.github.toolstem/toolstem-sec-mcp-server
SEC filing MCP for AI agents — insider signals, 13F flow, material events. Pre-computed.
Open source Open in the app JSON README (API)
About
SEC filing MCP for AI agents — insider signals, 13F flow, material events. Pre-computed.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- toolstem
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.9
- Stars
- 1
- Last push
- 2026-06-22T17:53:51Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:35
- Updated
- 2026-08-29 04:01:35
- Origin id
io.github.toolstem/toolstem-sec-mcp-server
README
# SEC EDGAR MCP Server — Insider Signals, 13D Activist Risk & Filing Intelligence
[](https://www.npmjs.com/package/toolstem-sec-mcp-server)
[](https://www.npmjs.com/package/toolstem-sec-mcp-server)
[](./LICENSE)
**SEC EDGAR intelligence for AI agents.** Five composite tools that pre-compute high-value signals directly from SEC EDGAR's public submissions API, returned as structured JSON.
> **No SEC API key required.** Data is sourced directly from SEC EDGAR's public submissions API. A built-in sliding-window rate limiter keeps traffic under SEC's 10 rps fair-access ceiling automatically.
---
## Quickstart — hosted endpoint (recommended)
Point your MCP client or agent at the hosted endpoint. **No API key, no infra, no setup.** Billing is per-call via [x402](https://www.x402.org) — the agent's wallet pays directly in USDC on Base mainnet.
```
https://mcp.toolstem.com/mcp/sec
```
- **No SEC API key, no signup, no marketplace account** — the agent's wallet pays directly.
- **No infrastructure** — nothing to install, host, or keep running.
- **No setup** — connect an MCP client and call a tool.
- `initialize` and `tools/list` are **free** (discovery and schema introspection).
- `tools/call` is **tiered per tool** (see [Pricing](#pricing) below).
### Claude Desktop
Drop this into your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"toolstem-sec": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.toolstem.com/mcp/sec"
]
}
}
}
```
Restart Claude Desktop, then ask: *"Has TSLA disclosed any material 8-K events in the last 90 days?"*
### Any MCP client (LangChain.js)
The official [`@langchain/mcp-adapters`](https://www.npmjs.com/package/@langchain/mcp-adapters) library connects directly to the hosted URL:
```ts
import { MultiServerMCPClient } from "@langchain/mcp-adapters";
import { ChatOpenAI } from "@langchain/openai";
import { createReactAgent } from "@langchain/langgraph/prebuilt";
const client = new MultiServerMCPClient({
toolstem_sec: {
transport: "http",
url: "https://mcp.toolstem.com/mcp/sec",
// Add your x402-signing middleware via headers, OR run an x402
// proxy locally and point url at it. See https://www.x402.org/clients.
},
});
const tools = await client.getTools();
const agent = createReactAgent({ llm: new ChatOpenAI({ model: "gpt-4o-mini" }), tools });
await agent.invoke({ messages: "Has TSLA disclosed any material 8-K events in the last 90 days?" });
```
### LangChain quick-start (`langchain-toolstem`)
The [`langchain-toolstem`](https://www.npmjs.com/package/langchain-toolstem) wrapper handles x402 payment for you — pass a funded wallet key and the SEC tools are included automatically:
```typescript
import { createToolstemTools } from 'langchain-toolstem';
const tools = await createToolstemTools({ walletPrivateKey: process.env.WALLET_KEY });
// SEC tools included automatically — agents pay per call in USDC
```
Prefer to run the server yourself over stdio/HTTP? See [Advanced: self-host](#advanced-self-host) at the bottom.
Try the tools live in the [Toolstem playground](https://www.toolstem.com/playground/).
---
## Pricing
- **MCP `initialize` and `tools/list` are free** — discover the server and its tool surface without paying anything.
- **`tools/call` is tiered per tool**, paid in USDC on Base mainnet via [x402](https://www.x402.org). No API key, no signup, no marketplace account — agents pay directly from their own wallet.
| Tier | Price per call | Tools |
|------|----------------|-------|
| Cheap | **$0.005** | `get_company_filings_summary` |
| Standard | **$0.05** | `get_insider_signal`, `get_institutional_signal` |
| Premium | **$0.50** | `get_material_events_digest`, `compare_disclosure_signals` |
Per-tool breakdown:
| Tool | Tier | Per call |
|------|------|----------|
| `get_company_filings_summary` | Standard | $0.005 USDC |
| `get_insider_signal` | Standard | $0.05 USDC |
| `get_institutional_signal` | Standard | $0.05 USDC |
| `get_material_events_digest` | Premium | $0.50 USDC |
| `compare_disclosure_signals` | Premium | $0.50 USDC |
### How billing works
Toolstem uses the x402 payment protocol. Agents pay per call in USDC on Base — no API keys, no subscriptions, no invoices. The agent's wallet settles each call automatically via EIP-3009.
See the live pricing page on [toolstem.com/sec/](https://toolstem.com/sec/) for current rates.
---
## The five tools
All five tools are composite/curated (they compute derived signals or aggregate across multiple EDGAR endpoints — no raw passthroughs). Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: true`.
| # | Tool | Required input | Optional input (default) | Tier (price/call) |
|---|------|----------------|--------------------------|-------------------|
| 1 | `get_company_filings_summary` | `ticker_or_cik` (string) | — | Cheap ($0.005) |
| 2 | `get_insider_signal` | `ticker_or_cik` (string) | `lookback_days` (int 1–730, **default 90**) | Standard ($0.05) |
| 3 | `get_institutional_signal` | `ticker_or_cik` (string) | `quarters_back` (int 1–20, **default 4**) | Standard ($0.05) |
| 4 | `get_material_events_digest` | `ticker_or_cik` (string) | `lookback_days` (int 1–1825, **default 365**) | **Premium ($0.50)** |
| 5 | `compare_disclosure_signals` | `tickers_or_ciks` (string[2..5]) | — | **Premium ($0.50)** |
---
### 1. `get_company_filings_summary`
Overview of a company's filing activity: last 20 filings + computed signals.
| Signal | Description |
|--------|-------------|
| `filing_velocity` | `ACCELERATING` / `NORMAL` / `SLOWING` vs. trailing 365-day average |
| `material_event_count_90d` | Count of 8-K filings in the last 90 days |
| `disclosure_volume_trend` | `RISING` / `STABLE` / `FALLING` based on 10-K size comparison |
| `latest_form_types` | Unique form types filed in the last 90 days |
**Example output (abbreviated):**
```json
{
"ticker": "AAPL",
"cik": "0000320193",
"company_name": "Apple Inc.",
"signals": {
"filing_velocity": "NORMAL",
"material_event_count_90d": 4,
"disclosure_volume_trend": "RISING",
"latest_form_types": ["8-K", "4", "DEF 14A"]
},
"meta": { "source": "sec_edgar_direct", "data_delay": "live" }
}
```
---
### 2. `get_insider_signal`
Probes Form 3 / 4 / 4/A insider filing activity within a configurable lookback window. Required: `ticker_or_cik`. Optional: `lookback_days` (1–730, default 90).
Returns: `recent_insider_filings[]` (accession numbers + SEC URLs), `net_transaction_count`, `buy_count`, `sell_count`, and `insider_signal`.
> **v0.1 limitation — counts only.** v0.1 returns counts and Form 4 references only; **direction-aware buy/sell signals ship in v0.2** (Form 4 XML parsing). Today, `insider_signal` is `null` when filings exist in the window (direction unknown) and `"NEUTRAL"` when no insider filings exist (verified absence). `buy_count` / `sell_count` are `0` in v0.1.
**Example output (abbreviated):**
```json
{
"ticker": "MSFT",
"cik": "0000789019",
"company_name": "MICROSOFT CORP",
"lookback_days": 90,
"insider_signal": null,
"net_transaction_count": 0,
"buy_count": 0,
"sell_count": 0,
"recent_insider_filings": [
{
"accession_number": "0001127602-26-001234",
"filing_date": "2026-04-15",
"sec_url": "https://www.sec.gov/Archives/edgar/data/789019/000112760226001234/0001127602-26-001234-index.htm"
}
],
"meta": { "source": "sec_edgar_direct", "data_delay": "live" }
}
```
---
### 3. `get_institutional_signal`
Probes for activist investor activity via SC 13D / 13D/A filings. Required: `ticker_or_cik`. Optional: `quarters_back` (1–20, default 4 ≈ 1 year).
| Field | Description |
|-------|-------------|
| `activist_risk_flag` | `true` if any SC 13D or 13D/A was filed in the last 365 days |
| `recent_13d_filings` | List of 13D filings with form type, date, and SEC URL |
> **v0.1 limitation — activist flag only.** v0.1 ships the **live `activist_risk_flag` (from 13D/13D-A)** and a list of 13D filings. Quarterly **13F XBRL parsing** — which produces `institutional_signal` (`ACCUMULATING` / `HOLDING` / `DISTRIBUTING`) and `recent_13f_count` — **ships in v0.2**. Today those two fields are `null` / `0`.
**Example output (abbreviated):**
```json
{
"ticker": "NVDA",
"cik": "0001045810",
"company_name": "NVIDIA CORP",
"quarters_back": 4,
"institutional_signal": null,
"recent_13f_count": 0,
"activist_risk_flag": false,
"recent_13d_filings": [],
"meta": { "source": "sec_edgar_direct", "data_delay": "live" }
}
```
---
### 4. `get_material_events_digest` ⚡ **Premium tier**
> **Premium tier — $0.50 USDC per call** on Base mainnet, settled via x402. See the live pricing page on [toolstem.com/sec/](https://toolstem.com/sec/) for current rates.
Severity-ranked digest of all 8-K and 8-K/A filings within a configurable lookback window. Each item code is mapped to a plain-English label and severity rating. Required: `ticker_or_cik`. Optional: `lookback_days` (1–1825, default 365).
| Severity | Examples |
|----------|---------|
| 🔴 RED | Cybersecurity incident (1.05), restatement (4.02), bankruptcy (1.03), delisting (3.01) |
| 🟡 YELLOW | Acquisition (2.01), new debt (2.03), executive departure (5.02) |
| 🟢 GREEN | Earnings release (2.02), Reg FD (7.01), shareholder vote (5.07) |
Returns: `events[]` (sorted newest-first), `redflag_count`, `category_counts`.
**Example output (abbreviated):**
```json
{
"ticker": "TSLA",
"cik": "0001318605",
"company_name": "Tesla, Inc.",
"lookback_days": 180,
"redflag_count": 1,
"category_counts": { "RED": 1, "YELLOW": 3, "GREEN": 7 },
"events": [
{
"accession_number": "0001628280-26-005678",
"filing_date": "2026-04-10",
"form": "8-K",
"items": [
{ "code": "4.02", "label": "Non-Reliance on Previously Issued Financial Statements", "category": "financial", "severity": "RED" }
],
"sec_url": "https://www.sec.gov/Archives/edgar/data/1318605/000162828026005678/0001628280-26-005678-index.htm"
}
],
"meta": { "source": "sec_edgar_direct", "data_delay": "live" }
}
```
---
### 5. `compare_disclosure_signals`
Side-by-side comparison of 2–5 companies across all key disclosure signals. Required: `tickers_or_ciks` (string[2..5]). All lookups run in parallel.
Returns per-company: `filing_velocity`, `material_event_count_90d`, `redflag_count_365d`, `activist_risk_flag`, `last_filing_date`.
Returns winners (as **CIKs**, not tickers — cross-reference with the `companies[]` array): `quietest_disclosure`, `most_active`, `most_redflags`, `activist_targets`.
**Example output (abbreviated):**
```json
{
"companies": [
{
"ticker": "AAPL",
"cik": "0000320193",
"filing_velocity": "NORMAL",
"material_event_count_90d": 4,
"redflag_count_365d": 0,
"activist_risk_flag": false,
"last_filing_date": "2026-04-25"
},
{
"ticker": "MSFT",
"cik": "0000789019",
"filing_velocity": "ACCELERATING",
"material_event_count_90d": 7,
"redflag_count_365d": 0,
"activist_risk_flag": false,
"last_filing_date": "2026-04-26"
}
],
"winners": {
"quietest_disclosure": "0000320193",
"most_active": "0000789019",
"most_redflags": null,
"activist_targets": []
},
"meta": { "source": "sec_edgar_direct", "data_delay": "live" }
}
```
---
## Advanced: self-host
> **Most users should use the [hosted endpoint](#quickstart--hosted-endpoint-recommended) above** — it needs no API key, no infrastructure, and no setup. This section is for users who specifically want to run the server themselves. When self-hosting you are responsible for running the process and for supplying an EDGAR fair-access contact (`SEC_USER_AGENT_CONTACT`).
### Claude Desktop (self-hosted over stdio)
Run locally over stdio — no x402 charges, you bring your own EDGAR fair-access contact:
```json
{
"mcpServers": {
"toolstem-sec": {
"command": "npx",
"args": ["-y", "toolstem-sec-mcp-server"],
"env": {
"SEC_USER_AGENT_CONTACT": "you@yourorg.com"
}
}
}
}
```
### npm (MCP stdio transport)
```bash
npm install -g toolstem-sec-mcp-server
toolstem-sec-mcp-server
```
### Self-hosted HTTP
Three modes:
**Local-only (default — safest):**
```bash
toolstem-sec-mcp-server --http
# Binds 127.0.0.1:3000 — reachable only from this machine
```
**Remote with auth:**
```bash
ALLOW_REMOTE=1 MCP_AUTH_TOKEN=my-secret toolstem-sec-mcp-server --http
# Binds 0.0.0.0:3000 — requires Bearer token on every /mcp request
```
**Remote without auth (use at your own risk):**
```bash
ALLOW_REMOTE=1 MCP_AUTH_DISABLED=1 toolstem-sec-mcp-server --http
# Binds 0.0.0.0:3000 — no authentication
```
| Variable | Description |
|----------|-------------|
| `PORT` | HTTP port (default `3000`) |
| `ALLOW_REMOTE` | Set to `1` to bind `0.0.0.0` instead of `127.0.0.1` |
| `MCP_AUTH_TOKEN` | Bearer token for `/mcp` routes (required when `ALLOW_REMOTE=1`) |
| `MCP_AUTH_DISABLED` | Set to `1` to skip auth even with `ALLOW_REMOTE=1` (not recommended) |
| `SEC_USER_AGENT_CONTACT` | Contact email for SEC EDGAR User-Agent header |
---
## SEC EDGAR fair-access policy
All outbound traffic goes through a shared sliding-window rate limiter (8 rps target, 4 rps safety margin below SEC's 10 rps hard cap). Every request includes a `User-Agent` header identifying the package and a contact email per SEC policy. Override the contact email via:
```bash
SEC_USER_AGENT_CONTACT=you@yourorg.com toolstem-sec-mcp-server
```
Violating SEC's fair-access policy can result in your IP being blocked. This server is designed to stay compliant automatically.
---
## v0.2 roadmap
- **Form 4 XML parsing** — direction-aware insider signals (`STRONG_BUYING` / `BUYING` / `NEUTRAL` / `SELLING` / `STRONG_SELLING`) with net share counts
- **13F XBRL parsing** — quarterly institutional flow signals (`ACCUMULATING` / `HOLDING` / `DISTRIBUTING`) with institution count
- **8-K text extraction** — natural-language summaries of each material event from the filing's primary HTML document
---
## License & author
MIT License — see [LICENSE](./LICENSE).
Built by [Toolstem](https://toolstem.com/sec/). Data sourced directly from [SEC EDGAR](https://www.sec.gov/developer).