edgaralert

EDGAR Alert MCP 服务

将 Claude Desktop（或任何兼容 MCP 的 客户端）直接连接到你的 EDGAR Alert 账户。无需离开 当前对话，即可询问 SEC 内部人交易信号、Form 4 活动、8-K 高管／董事变动以及公司研究背景的实时问题。

适用于任何付费 EDGAR Alert 套餐。 大多数工具（最新提醒、 搜索、公司档案、基本面、价格区间）适用于 STARTER 和 PRO。一个工具——edgaralert_get_company_agent_context，用于获取整合后的 AI 研究背景数据——需要 Enterprise 套餐；在较低级别的套餐上，它会返回明确的升级提示，而不是悄无声息地失败。完整说明请参阅下文的 工具，如需升级，请访问 edgaralert.com/pricing。

这是什么（以及不是什么）

• 现有公开 https://api.edgaralert.com/api/v1 REST API 的轻量封装。每个工具都对应且仅对应一个 v1 端点。
• 不直接访问数据库。 这里不会重复实现任何评分或信号逻辑——这些逻辑全部位于 API 中，与所有其他 v1 API 调用方使用的相同。
• 不处理计费、账户管理或交易。 此服务无法下单、更改你的订阅或修改账户设置。
• 两个工具会写入数据，且仅会写入你自己的观察列表。 edgaralert_add_ticker_to_list 和 edgaralert_remove_ticker_from_list 会对 /ticker-lists 执行 POST 和 DELETE 操作。其他操作均为 GET。
• API 密钥由你自行保管——由你提供，仅作为 X-API-Key 请求头发送至 api.edgaralert.com，此服务绝不会将其写入磁盘或日志。

要求

• Node.js 18.17 或更高版本
• 任意付费套餐的 EDGAR Alert API 密钥 （在此获取）——大多数工具均适用于 STARTER 和 PRO；Enterprise 可解锁全部 8 个工具。

安装

选项 A：通过 .mcpb 一键安装（推荐大多数用户使用）

1. 从 最新版本发布页下载 edgaralert-mcp.mcpb。
2. 打开 Claude Desktop → Settings → Extensions → Advanced settings → Install Extension，然后选择下载的文件（或直接将文件拖到 Claude Desktop 窗口中）。
3. 出现提示时，粘贴你的 EDGAR Alert API 密钥。Claude Desktop 会将其 安全地存储在操作系统的密钥链中——除该提示步骤外，本项目不会接触或存储此密钥。
4. 如有提示，请重启 Claude Desktop。

选项 B：通过 claude_desktop_config.json 手动安装

1. 将此文件夹（mcp-server/）克隆或下载到你计算机上的某个位置。

2. 安装依赖并构建：

   cd mcp-server
   npm install
   npm run build
   

3. 打开 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

4. 在 mcpServers 下添加一项（参见下方示例）。

5. 重启 Claude Desktop。

选项 C：在本地运行以进行开发

cd mcp-server
npm install
EDGARALERT_API_KEY=EA_your_key_here npm run dev

此命令使用 tsx 通过 stdio 运行服务，无需构建步骤。适用于 迭代工具定义。

Claude Desktop 配置示例

{
  "mcpServers": {
    "edgaralert": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "EDGARALERT_API_KEY": "EA_your_key_here"
      }
    }
  }
}

将 /absolute/path/to/mcp-server/dist/index.js 替换为你计算机上的实际路径， 并将 EA_your_key_here 替换为你的 EDGAR Alert API 密钥。 切勿提交包含真实密钥的此文件。

环境变量

变量	必需	默认值	描述
EDGARALERT_API_KEY	是	—	你的 EDGAR Alert v1 API 密钥。每次请求都会通过 X-API-Key 发送。
EDGARALERT_BASE_URL	否	https://api.edgaralert.com/api/v1	用于覆盖暂存环境或本地开发环境。大多数用户无需设置此项。

工具

12 个工具中有 10 个为只读工具；以下标记为 write 的两个观察名单变更工具除外。完整的输入架构、端点映射和错误行为，请参阅 docs/tools.md。

工具	端点	最低套餐
edgaralert_get_latest_alerts	GET /alerts/latest	STARTER
edgaralert_search_alerts	GET /alerts	PRO
edgaralert_get_alert_price_window	GET /alerts/{id}/price-window	PRO
edgaralert_search_companies	GET /companies/search	PRO
edgaralert_get_company_profile	GET /companies/{tickerOrCik}/profile	所有付费套餐
edgaralert_get_company_fundamentals	GET /companies/{tickerOrCik}/fundamentals	PRO
edgaralert_get_company_agent_context	GET /companies/{tickerOrCik}/agent-context	ENTERPRISE
edgaralert_get_weekly_insights	GET /insights/weekly（公开）	无
edgaralert_get_industry_capital_flow	GET /insights/capital-flow（公开）	无
edgaralert_get_ticker_lists	GET /ticker-lists	STARTER
edgaralert_add_ticker_to_list	POST /ticker-lists/{listId}/items (write)	STARTER
edgaralert_remove_ticker_from_list	DELETE /ticker-lists/{listId}/items/{ticker} (write)	STARTER

“最低套餐”反映了底层 API 当前执行的要求——STARTER 和 PRO 密钥可使用 12 个工具中的 11 个。只有 edgaralert_get_company_agent_context 要求 Enterprise；使用较低套餐的密钥调用时，它会返回清晰的 403 错误和升级提示（见下文），而不是静默失败或崩溃。两个 /insights/* 工具是公开的，无需任何套餐。

你可能会遇到的错误

• "Your EDGAR Alert API key was rejected" — 检查是否已设置 EDGARALERT_API_KEY，且其值正确。
• "This action requires a higher EDGAR Alert plan" — 对于使用 STARTER/PRO 密钥调用 edgaralert_get_company_agent_context，这是预期情况；这些套餐下的其他工具都应正常工作。如果其他工具出现此错误，请在 EDGAR Alert 控制面板中仔细检查你的套餐等级。
• "rate or daily quota exceeded" — 你已达到套餐的 API 限制。请稍后再试，或在 EDGAR Alert 控制面板中查看用量。
• "Could not reach the EDGAR Alert API" — 这是网络/连接问题，并非账户问题。运行 node -e "fetch('https://api.edgaralert.com/api/v1/alerts/latest').then(r=>r.text()).then(console.log)" — 你应该会看到类似 {"message":"Missing X-API-Key header."} 的 JSON 错误（这是预期情况，表示 API 可以访问）。如果出现 DNS 错误（ENOTFOUND/ENODATA）或没有响应，问题出在本地网络/DNS，而非此服务或你的账户。
• "Unexpected token '<', is not valid JSON" — 请求已到达服务，但返回的是 HTML 页面，而非 API 数据。如果 EDGARALERT_BASE_URL 被设为 edgaralert.com 或 www.edgaralert.com，而不是 api.edgaralert.com，就会发生这种情况：裸域名和 www 主机提供的是营销网站（Azure Static Web App），而非 API。此软件包中的默认值已设为 api.edgaralert.com；如果看到此错误，请检查配置中的 EDGARALERT_BASE_URL 是否被覆盖。

安全说明

• 此服务不具备任何管理、计费或订单管理功能——这是有意为之，这些端点未在此处实现。
• 此软件包中没有硬编码任何密钥。唯一使用的凭据是你通过环境变量 / Claude Desktop 配置提供的凭据。
• 工具调用之间不会缓存数据，也不会将数据持久化到磁盘。
• 网络访问仅限于 EDGARALERT_BASE_URL（默认为 api.edgaralert.com）——不会进行其他出站调用。

开发

npm run typecheck   # type-check without emitting
npm run build        # compile to dist/
npm run dev           # run with tsx, no build step

要添加新工具：对于无输入工具，请参照 src/tools/getWeeklyInsights.ts 中的模式；对于带筛选条件的工具，请参照 src/tools/searchAlerts.ts 中的模式。然后在 src/tools/index.ts 中注册，并且只能调用 api/v1/* 或其他已公开的端点。请勿在此软件包中添加数据库客户端、Stripe/订单客户端或任何具有写入能力的工具。