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

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

Environment Variables

* 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

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