Which integrations are available for this server?

Provides SEC financial data tools within VS Code via GitHub Copilot, enabling AI-assisted analysis of filings, insider trades, and institutional holdings.

How do I use secapi-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@secapi-mcp search for Apple's latest 10-Q filing" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

secapi-mcp

Official

by secapi-dev

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

secapi-mcp

Official Model Context Protocol server for secapi.dev.

Expose SEC filings, financial statements, insider trades, and institutional holdings as AI-native tools for Claude, Cursor, ChatGPT, Windsurf, VS Code, and any MCP-compatible client.

AI Client  →  MCP Tools  →  secapi.dev REST API  →  JSON Response  →  LLM

This server never talks to databases directly — it is a typed, validated interface over the secapi-node SDK.

Features

9 high-level AI tools designed for reasoning, not REST endpoint mirroring
SDK-first architecture — all API calls go through secapi-node
Zod validation on every tool input
AI-friendly errors with categories, suggestions, and retry hints
Structured JSON responses with metadata and pagination
Extensible tool registry — add new tools in minutes
Production logging — structured, secrets-safe
Full test suite with Vitest
CI/CD with GitHub Actions and Changesets

Related MCP server: FinResearch MCP

Installation

npm install -g secapi-mcp
# or
pnpm add -g secapi-mcp
# or run via npx
npx secapi-mcp

Requires Node.js 20+.

Quick Start

Get an API key from secapi.dev
Set your environment variable:

export SECAPI_API_KEY="your-api-key"

Run the server (stdio transport):

secapi-mcp

MCP Client Configuration

Cursor

Add to .cursor/mcp.json (or Cursor Settings → MCP):

{
  "mcpServers": {
    "secapi": {
      "command": "npx",
      "args": ["-y", "secapi-mcp"],
      "env": {
        "SECAPI_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "secapi": {
      "command": "npx",
      "args": ["-y", "secapi-mcp"],
      "env": {
        "SECAPI_API_KEY": "your-api-key"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to your VS Code MCP settings:

{
  "mcp": {
    "servers": {
      "secapi": {
        "command": "npx",
        "args": ["-y", "secapi-mcp"],
        "env": {
          "SECAPI_API_KEY": "your-api-key"
        }
      }
    }
  }
}

Windsurf

Add to Windsurf MCP configuration:

{
  "mcpServers": {
    "secapi": {
      "command": "npx",
      "args": ["-y", "secapi-mcp"],
      "env": {
        "SECAPI_API_KEY": "your-api-key"
      }
    }
  }
}

Available Tools

Tool	Description
`search_filings`	Search SEC filings by ticker/CIK, form type, and date range
`analyze_filing`	Get filing metadata and document list for deeper analysis
`search_companies`	Search companies by name, ticker, or CIK
`company_overview`	Company profile plus recent filings — ideal research starting point
`company_financials`	Income statement, balance sheet, or cash flow
`company_ratios`	Financial ratio time series (ROE, margins, liquidity, etc.)
`insider_trades`	Insider buying/selling activity from Form 4 filings
`search_institutions`	Find institutional investors (13F filers)
`institution_holdings`	13F portfolio holdings for a given quarter

Environment Variables

Variable	Required	Default	Description
`SECAPI_API_KEY`	Yes*	—	API key from secapi.dev
`SEC_API_KEY`	Yes*	—	Legacy alias for `SECAPI_API_KEY`
`SECAPI_BASE_URL`	No	`https://api.secapi.dev`	API base URL
`SECAPI_TIMEOUT_MS`	No	`30000`	Request timeout in milliseconds
`SECAPI_MAX_RETRIES`	No	`2`	Retry count for transient failures
`SECAPI_DEBUG`	No	`false`	Enable debug logging to stderr
`SECAPI_USER_AGENT`	No	`secapi-mcp/0.1.0`	User-Agent header

* One of SECAPI_API_KEY or SEC_API_KEY is required.

Architecture

src/
├── index.ts              # stdio entry point
├── server/               # MCP server factory
├── client/               # secapi-node wrapper
├── config/               # Zod-validated configuration
├── errors/               # AI-friendly error categorization
├── logging/              # Structured, secrets-safe logging
├── schemas/              # Shared Zod schemas
├── utils/                # Response formatting
└── tools/
    ├── registry.ts       # Tool registration system
    ├── types.ts          # Tool definition interfaces
    ├── filings/          # Filing tools
    ├── companies/        # Company tools
    ├── financials/       # Financial statement tools
    ├── insiders/         # Insider trading tools
    └── institutions/     # 13F institutional tools

Adding a New Tool

Create a tool definition in the appropriate src/tools/<domain>/index.ts:

{
  name: "my_new_tool",
  description: "Clear description for the LLM...",
  inputSchema: z.object({ ticker: tickerSchema }),
  handler: async (input, { client }) => {
    const data = await client.filings.search({ ticker: input.ticker });
    return createToolResponse("my_new_tool", data.data, {
      pagination: data.pagination,
    });
  },
}

Export the module from src/tools/index.ts if it's a new domain.

That's it — the registry handles validation, error formatting, and MCP registration.

Development

git clone https://github.com/secapi-dev/secapi-mcp.git
cd secapi-mcp
pnpm install
pnpm test
pnpm build

Run locally:

SECAPI_API_KEY=your-key pnpm start

Scripts

Script	Description
`pnpm build`	Build to `dist/`
`pnpm test`	Run Vitest test suite
`pnpm typecheck`	TypeScript type checking
`pnpm lint`	ESLint
`pnpm format`	Prettier format

Troubleshooting

"API key is required" — Set SECAPI_API_KEY in your MCP client config env block.

"Invalid or missing API key" — Verify your key at secapi.dev. Keys are never logged.

"API rate limit exceeded" — Wait and retry, or upgrade your plan.

Server not appearing in Cursor — Restart Cursor after editing MCP config. Check stderr logs with SECAPI_DEBUG=true.

FAQ

Why not mirror REST endpoints 1:1? AI agents work better with semantic, high-level tools. company_overview is more useful than GET /entities/:id + GET /entities/:id/filings.

Can I self-host? Yes. Set SECAPI_BASE_URL if using a custom API deployment.

How do I add more tools? See Adding a New Tool. The framework is designed for fast extension.

License

MIT — see LICENSE.

Available Tools

9 tools

analyze_filingA

Retrieve a filing's metadata and list of attached documents (HTML, XBRL, exhibits). Use when you need to understand filing contents before deeper analysis. Requires CIK and accession number.

Examples:

analyze_filing({ cik: "0000320193", accessionNumber: "0000320193-24-000123" })

Inputs: cik (required), accessionNumber (required).

company_financialsA

Retrieve standardized financial statements for a company — income statement, balance sheet, or cash flow. Uses the latest available filing when no accession number is provided.

Examples:

company_financials({ identifier: "MSFT", statement: "income" })
company_financials({ identifier: "AAPL", statement: "balance" })

Inputs: identifier (required), statement, accessionNumber.

company_overviewB

Get a comprehensive overview of a public company by ticker or CIK, including recent SEC filings. Ideal starting point for company research.

Examples:

company_overview({ identifier: "AAPL" })
company_overview({ identifier: "0000320193", filingLimit: 10 })

Inputs: identifier (required), filingLimit.

company_ratiosB

Get financial ratio time series for a company (profitability, liquidity, leverage, efficiency). Useful for valuation and comparative analysis.

Examples:

company_ratios({ identifier: "AAPL", ratio: "roe" })
company_ratios({ identifier: "GOOGL", limit: 12 })

Inputs: identifier (required), limit, ratio.

insider_tradesB

Search insider trading transactions (Form 4 filings) by company ticker. Filter by buy/sell activity, transaction type, and date range. Returns officer and director trades.

Examples:

insider_trades({ ticker: "TSLA", activity: "buying", limit: 10 })
insider_trades({ ticker: "NVDA", activity: "latest" })

Inputs: ticker (required), limit, endDate, activity, +2 more.

institution_holdingsA

Get an institutional investor's 13F portfolio holdings for a given quarter. Shows positions, share counts, and market values. Requires institution CIK.

Examples:

institution_holdings({ cik: "0001067983", quarter: "2024-Q3" })
institution_holdings({ cik: "0001166559", limit: 50, sort: "weight" })

Inputs: cik (required), sort, limit, quarter.

search_companiesA

Search SEC-registered companies by name, ticker, or CIK. Returns entity metadata including company name, ticker, CIK, and entity type.

Examples:

search_companies({ query: "Apple" })
search_companies({ ticker: "MSFT" })

Inputs: cik, page, limit, query, +1 more.

search_filingsA

Search SEC EDGAR filings by company ticker or CIK. Filter by form type (10-K, 10-Q, 8-K, etc.) and date range. Use for discovering recent or historical regulatory filings.

Examples:

search_filings({ ticker: "AAPL", form: ["10-K", "10-Q"], limit: 5 })
search_filings({ cik: "0000320193", startDate: "2024-01-01" })

Inputs: cik, form, page, limit, +3 more.

search_institutionsA

Search institutional investment managers (13F filers) by name or CIK. Returns hedge funds, asset managers, and other institutions that file Form 13F.

Examples:

search_institutions({ query: "Berkshire" })
search_institutions({ query: "Vanguard", limit: 5 })

Inputs: page, limit, query.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored 2026-07-16 09:56 across 9 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: filing analysis, financials, company overview, ratios, insider trades, institutional holdings, and search functions for companies, filings, and institutions. No overlapping responsibilities.

Naming Consistency4/5

All tool names use snake_case, but there is a mix of verb-first (analyze_filing, search_*) and noun-first (company_*, institution_holdings) patterns. While readable, the inconsistency prevents a perfect score.

Tool Count5/5

With 9 tools, the server covers the essential SEC data retrieval operations without being bloated or too sparse. Each tool serves a well-defined need.

Completeness4/5

Core SEC filing and company data operations are covered (search, retrieve, analyze). Minor gaps exist, such as direct XBRL data extraction or historical filing comparisons, but the surface is largely complete for common workflows.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

FiledProofA
com.davisvillelabs.filedproof
Primary-source SEC filing intelligence and financial/disclosure reconciliation for AI agents.
Finance Government Data Research & Data
1
https://filedproof.davisvillelabs.com/mcp
plainyogurt21-sec-edgar-mcp
ai.smithery
Provide AI assistants with real-time access to official SEC EDGAR filings and financial data. Enab…
Finance Government Data Open Data
21
https://server.smithery.ai/@plainyogurt21/sec-edgar-mcp/mcp
Flori Financial Data APIA
io.github.goosemafia22-rgb
SEC EDGAR financials, insider trading, and economic data for AI agents. US GAAP + IFRS.
Finance Government Data
2
https://steve-12ad36b4.base44.app/functions/floriMCP
ko-mcpA
io.github.SharpLu
Real SEC, 13F, insider, congress & macro data your AI agent can cite. Hosted MCP, 24 tools.
Finance Government Data
322
https://mcp.ko.io/mcp

Related MCP Servers

SEC EDGAR MCP Server
Sejin-Koo
A
license
Not graded
quality
D
maintenance
Enables to search and retrieve SEC EDGAR filings, insider transactions, major shareholders, and executive compensation data through natural language.
Updated 3 months ago (2026-08-13 09:01 UTC)
12 npm
MIT
FinResearch MCP
Finance Research & Data Data Visualization
ritam003-roy
F
license
B
quality
Not graded
maintenance
Enables SEC EDGAR financial research, analysis, valuation, and chart data generation through natural language.
Updated 4 months ago (2026-07-23 23:33 UTC)
24
-
octagon-mcp-server
Finance Research & Data Search
Nikolai603
F
license
Not graded
quality
A
maintenance
Enables natural-language research and structured, source-backed answers across SEC filings, earnings transcripts, company financials, stock and crypto market data, and prediction markets news and research.
Updated a month ago (2026-10-16 10:09 UTC)
-
octagon-mcp-server
Finance Research & Data Search
Dijkstra41327
A
license
Not graded
quality
A
maintenance
Enables users to ask natural-language questions and receive structured, source-backed answers across SEC filings, earnings transcripts, company financials, stock and crypto market data, and prediction markets news and research.
Updated a month ago (2026-10-18 06:48 UTC)
MIT

secapi-mcp

Features

Installation

Quick Start

MCP Client Configuration

Cursor

Claude Desktop

VS Code (GitHub Copilot)

Windsurf

Available Tools

Environment Variables

Architecture

Adding a New Tool

Development

Scripts

Troubleshooting

FAQ

License

Links

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

SEC EDGAR MCP Server

FinResearch MCP

octagon-mcp-server

octagon-mcp-server