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

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

1. Get an API key from secapi.dev

2. Set your environment variable:

export SECAPI_API_KEY="your-api-key"

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

1. 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,
    });
  },
}

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

Links

• secapi.dev — API platform
• secapi-node — TypeScript SDK
• Model Context Protocol — MCP specification