Content
# secapi-mcp
Official [Model Context Protocol](https://modelcontextprotocol.io) server for [**secapi.dev**](https://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`](https://www.npmjs.com/package/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
```bash
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](https://secapi.dev)
2. Set your environment variable:
```bash
export SECAPI_API_KEY="your-api-key"
```
3. Run the server (stdio transport):
```bash
secapi-mcp
```
## MCP Client Configuration
### Cursor
Add to `.cursor/mcp.json` (or Cursor Settings → MCP):
```json
{
"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):
```json
{
"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:
```json
{
"mcp": {
"servers": {
"secapi": {
"command": "npx",
"args": ["-y", "secapi-mcp"],
"env": {
"SECAPI_API_KEY": "your-api-key"
}
}
}
}
}
```
### Windsurf
Add to Windsurf MCP configuration:
```json
{
"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`:
```typescript
{
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
```bash
git clone https://github.com/secapi-dev/secapi-mcp.git
cd secapi-mcp
pnpm install
pnpm test
pnpm build
```
Run locally:
```bash
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](https://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](#adding-a-new-tool). The framework is designed for fast extension.
## License
MIT — see [LICENSE](LICENSE).
## Links
- [secapi.dev](https://secapi.dev) — API platform
- [secapi-node](https://www.npmjs.com/package/secapi-node) — TypeScript SDK
- [Model Context Protocol](https://modelcontextprotocol.io) — MCP specification
