内容
# secapi-mcp
官方 [模型上下文协议](https://modelcontextprotocol.io) 服务器，用于 [**secapi.dev**](https://secapi.dev).
公开 SEC 文件、财务报表、内幕交易和机构持仓，作为适用于 Claude、Cursor、ChatGPT、Windsurf、VS Code 和任何 MCP 兼容客户端的 AI 原生工具。
```
AI 客户端 → MCP 工具 → secapi.dev REST API → JSON 响应 → LLM
```
此服务器 **从不** 直接与数据库通信 - 它是 `secapi-node` SDK 的类型化、验证接口。
## 功能
- **9种高级AI工具**，设计用于推理，而非REST端点镜像
- **SDK优先架构** - 所有API调用都通过 `secapi-node`
- **Zod验证**，适用于每个工具输入
- **AI友好错误**，包含类别、建议和重试提示
- **结构化JSON响应**，包含元数据和分页
- **可扩展的工具注册表** - 几分钟内添加新工具
- **生产日志** - 结构化、安全的密钥
- **完整的测试套件**，使用 Vitest
- **CI/CD**，使用 GitHub Actions 和 Changesets
## 安装
```bash
npm install -g secapi-mcp
# 或
pnpm add -g secapi-mcp
# 或使用 npx 运行
npx secapi-mcp
```
需要 Node.js 20+。
## 快速入门
1. 从 [secapi.dev](https://secapi.dev) 获取 API 密钥
2. 设置环境变量：
```bash
export SECAPI_API_KEY="your-api-key"
```
3. 运行服务器（stdio 传输）：
```bash
secapi-mcp
```
## MCP 客户端配置
### Cursor
添加到 `.cursor/mcp.json`（或 Cursor 设置 → MCP）：
```json
{
"mcpServers": {
"secapi": {
"command": "npx",
"args": ["-y", "secapi-mcp"],
"env": {
"SECAPI_API_KEY": "your-api-key"
}
}
}
}
```
### Claude 桌面版
添加到 `~/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）
添加到您的 VS Code MCP 设置：
```json
{
"mcp": {
"servers": {
"secapi": {
"command": "npx",
"args": ["-y", "secapi-mcp"],
"env": {
"SECAPI_API_KEY": "your-api-key"
}
}
}
}
}
```
### Windsurf
添加到 Windsurf MCP 配置：
```json
{
"mcpServers": {
"secapi": {
"command": "npx",
"args": ["-y", "secapi-mcp"],
"env": {
"SECAPI_API_KEY": "your-api-key"
}
}
}
}
```
## 可用工具
| 工具 | 描述 |
| --- | --- |
| `search_filings` | 按股票代码/CIK、表格类型和日期范围搜索SEC文件 |
| `analyze_filing` | 获取文件元数据和文档列表以进行深入分析 |
| `search_companies` | 按名称、股票代码或CIK搜索公司 |
| `company_overview` | 公司简介 + 最近的文件 - 理想的研究起点 |
| `company_financials` | 损益表、资产负债表或现金流量表 |
| `company_ratios` | 财务比率时间序列（ROE、利润率、流动性等） |
| `insider_trades` | 从Form 4文件获取内幕买卖活动 |
| `search_institutions` | 查找机构投资者（13F文件填报者） |
| `institution_holdings` | 给定季度的13F投资组合持仓 |
## 环境变量
| 变量 | 必需 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `SECAPI_API_KEY` | 是* | - | secapi.dev 的 API 密钥 |
| `SEC_API_KEY` | 是* | - | `SECAPI_API_KEY` 的旧别名 |
| `SECAPI_BASE_URL` | 否 | `https://api.secapi.dev` | API 基地址 |
| `SECAPI_TIMEOUT_MS` | 否 | `30000` | 请求超时毫秒数 |
| `SECAPI_MAX_RETRIES` | 否 | `2` | 暂时性故障的重试次数 |
| `SECAPI_DEBUG` | 否 | `false` | 启用 stderr 中的调试日志 |
| `SECAPI_USER_AGENT` | 否 | `secapi-mcp/0.1.0` | 用户代理头 |
\* `SECAPI_API_KEY` 或 `SEC_API_KEY` 之一是必需的。
## 架构
```
src/
├── index.ts # stdio 入口点
├── server/ # MCP 服务器工厂
├── client/ # secapi-node 包装器
├── config/ # Zod 验证配置
├── errors/ # AI 友好错误分类
├── logging/ # 结构化、安全的密钥日志记录
├── schemas/ # 共享 Zod 模式
├── utils/ # 响应格式化
└── tools/
├── registry.ts # 工具注册系统
├── types.ts # 工具定义接口
├── filings/ # 文件工具
├── companies/ # 公司工具
├── financials/ # 财务报表工具
├── insiders/ # 内幕交易工具
└── institutions/ # 13F 机构工具
```
### 添加新工具
1. 在相应的 `src/tools/<domain>/index.ts` 中创建工具定义：
```typescript
{
name: "my_new_tool",
description: "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. 如果是新域，请从 `src/tools/index.ts` 导出模块。
就是这样 - 注册表处理验证、错误格式化和 MCP 注册。
## 开发
```bash
git clone https://github.com/secapi-dev/secapi-mcp.git
cd secapi-mcp
pnpm install
pnpm test
pnpm build
```
在本地运行：
```bash
SECAPI_API_KEY=your-key pnpm start
```
## 脚本
| 脚本 | 描述 |
| --- | --- |
| `pnpm build` | 构建到 `dist/` |
| `pnpm test` | 运行 Vitest 测试套件 |
| `pnpm typecheck` | TypeScript 类型检查 |
| `pnpm lint` | ESLint |
| `pnpm format` | Prettier 格式 |
## 故障排除
**"API 密钥是必需的"** - 在您的 MCP 客户端配置 `env` 块中设置 `SECAPI_API_KEY`。
**"无效或丢失的 API 密钥"** - 在 [secapi.dev](https://secapi.dev) 上验证您的密钥。密钥永远不会被记录。
**"API 速率限制已超过"** - 等待并重试，或升级您的计划。
**Cursor 中未显示服务器** - 编辑 MCP 配置后重启 Cursor。 使用 `SECAPI_DEBUG=true` 检查 stderr 日志。
## 常见问题
**为什么不直接镜像 REST 端点？**
AI 代理使用语义、高级工具的效果更好。`company_overview` 比 `GET /entities/:id` + `GET /entities/:id/filings` 更有用。
**我可以自行托管吗？**
是的。 如果使用自定义 API 部署，请设置 `SECAPI_BASE_URL`。
**如何添加更多工具？**
请参阅 [添加新工具](#添加新工具)。 该框架旨在快速扩展。
## 许可证
MIT - 请参阅 [LICENSE](LICENSE).
## 链接
- [secapi.dev](https://secapi.dev) - API 平台
- [secapi-node](https://www.npmjs.com/package/secapi-node) - TypeScript SDK
- [模型上下文协议](https://modelcontextprotocol.io) - MCP 规范
