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