BoomTax

BoomTax MCP 服务

面向 Claude、ChatGPT、Codex、Cursor、Windsurf、VS Code Copilot 及其他 Model Context Protocol 客户端的 BoomTax 只读申报工具。

托管端点为 **https://api.boomtax.com/mcp**，使用 Streamable HTTP 和 OAuth。必须在你的 BoomTax 账户中启用 API 访问权限；如有需要，请联系 [email protected]。

发布状态（2026 年 10 月 9 日）：托管 API 更新已部署，远程服务已在官方 MCP Registry 中发布，名称为 io.github.boomtax/mcp-server，版本为 2.0.0。npm 2.0.0 客户端尚未发布；npm 1.0.0 使用旧版密码认证。请使用远程连接，或从此源代码树运行本地客户端。有关客户端验证和待完成的发布工作，请参阅发布验证。

工具

工具	描述
list_filings	按年份、表单类型和状态筛选申报；包含申报系统
get_filing_details	申报详情、付款方摘要和电子申报状态
get_filing_summary	按状态和表单类型统计数量
list_filing_forms	分页列出申报中的表单元数据
get_form	表单元数据、状态和日期
get_efile_status	电子申报请求和响应时间线
get_efile_errors	电子申报错误和消息
list_payers	可访问申报中的付款方
get_payer	付款方详情，包括已遮蔽的付款方 TIN
list_filing_types	可用的申报类型、纳税年度和申报系统

这些工具无法创建、编辑、删除或提交申报。本地客户端会将这十个工具转发到托管服务，并阻止其他工具名称。请使用 list_filing_types 获取当前可用的表单，而不要依赖每个纳税年度都可能过时的静态列表。

设置

远程连接（推荐）

在支持 Streamable HTTP 和基于 PKCE 的 OAuth 的客户端中使用 https://api.boomtax.com/mcp。按提示完成浏览器登录。OAuth 客户端注册使用 Dynamic Client Registration（DCR）；如果客户端提供 DCR 和已发布客户端身份之间的选择，请选择自动注册。目前不支持 Client ID Metadata Documents（CIMD）。

发现端点：

• https://api.boomtax.com/.well-known/oauth-protected-resource
• https://api.boomtax.com/.well-known/oauth-authorization-server

未经身份验证打开 /mcp 时收到 401 响应是预期行为。响应中包含 WWW-Authenticate 发现标头。在浏览器中直接打开 URL 并不能测试经过身份验证的连接。

本地客户端（版本 2）

需要 Node.js 22 或更高版本。请在 BoomTax API 凭据中创建只读权限的 API 凭据。通过客户端的机密存储或环境提供这些值：

变量	必需	用途
BOOMTAX_CLIENT_ID	是	API 凭据客户端 ID
BOOMTAX_CLIENT_SECRET	是	API 凭据密钥
BOOMTAX_API_URL	否	默认为 https://api.boomtax.com；请指定源站，而不是 /mcp

客户端会获取短期 OAuth 令牌，并在令牌过期时重新进行身份验证。它不使用账户邮箱/密码。仅允许通过 HTTP 连接本地回环开发服务器；其他源站都必须使用 HTTPS。

设置上述环境变量后，运行源代码版本：

git clone https://github.com/boomtax/mcp-server.git
cd mcp-server
npm ci
node index.js

2.0.0 版本发布后，对应的包命令为：

npx -y @boomtax/[email protected]

在 Windows 上，无法直接启动 npx 的客户端可以使用 cmd /c npx -y @boomtax/[email protected]，或者使用 node 和 index.js 的绝对路径调用已安装的客户端。

按 AI 客户端配置

Claude Desktop 和 Claude web

要建立远程连接，请打开 Connectors，添加自定义连接器，并输入 https://api.boomtax.com/mcp。选择自动 OAuth 客户端注册并完成登录。组织账户可能需要管理员先添加连接器。远程连接器通过连接器界面配置，而不是通过 claude_desktop_config.json 中仅填写 URL 的方式配置。

要在 Claude Desktop 中从本地源代码安装，请使用绝对路径，并安全注入两个凭据环境变量：

{
  "mcpServers": {
    "boomtax": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/index.js"],
      "env": {
        "BOOMTAX_CLIENT_ID": "YOUR_READ_SCOPED_CLIENT_ID",
        "BOOMTAX_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

请将包含机密的文件保存在源代码管理之外。JSON 中的 Windows 路径需要使用双反斜杠或正斜杠。

Claude Code

claude mcp add boomtax --transport http https://api.boomtax.com/mcp

在 Claude Code 中使用 /mcp 完成身份验证。

ChatGPT

在允许自定义 MCP 连接的工作区中，添加自定义连接器或插件，URL 填写 https://api.boomtax.com/mcp，选择 OAuth 和自动客户端注册，然后完成登录。具体界面和可用性取决于工作区设置。如果系统要求使用预注册的 OAuth 客户端，请联系 BoomTax 支持；机器到机器 API 凭据并非授权码客户端注册。

Codex

codex mcp add boomtax --url https://api.boomtax.com/mcp
codex mcp login boomtax

Codex 使用托管服务的 OAuth 发现元数据。本地 stdio 客户端也可以通过 node 运行上述源代码路径，并从其环境中继承 BOOMTAX_CLIENT_ID 和 BOOMTAX_CLIENT_SECRET。

Cursor 和 Windsurf

将此远程服务添加到客户端的 MCP 配置中，然后完成 OAuth 登录：

{
  "mcpServers": {
    "boomtax": {
      "url": "https://api.boomtax.com/mcp"
    }
  }
}

Cursor 使用 .cursor/mcp.json。在 Windsurf 或 Devin Desktop 中，使用 MCP 设置中的 Open MCP config file 操作，选择适用于已安装版本的配置。如果客户端版本不支持远程服务的 OAuth，请改用本地源代码配置。

VS Code / GitHub Copilot

添加到 .vscode/mcp.json：

{
  "servers": {
    "boomtax": {
      "type": "http",
      "url": "https://api.boomtax.com/mcp"
    }
  }
}

从 VS Code 的 MCP 控件启动服务，并完成 OAuth 登录。此配置不包含账户机密。

示例提示词

• “2025 纳税年度有哪些申报？”
• “按状态汇总我的申报。”
• “此申报的电子申报状态是什么？”
• “显示我的 1099-NEC 申报中的错误。”
• “有哪些申报类型和纳税年度可用？”

安全与故障排查

• 数据访问范围仅限经过身份验证的账户及其申报权限。
• 托管服务会屏蔽结构化付款方 TIN 字段。结果仍包含机密姓名、联系方式和申报信息；仅与获授权的助手共享。
• 每个本地集成都使用单独的只读 API 凭据，不再需要时请在 BoomTax 中撤销。
• 本地客户端会将凭据保存在内存中。它会将 OAuth 发现固定到配置的 API 颁发者，并且不会记录上游错误正文或凭据。
• 本地启动失败通常表示客户端凭据缺失、API 访问已禁用或 API 无法访问。请勿提供 BOOMTAX_API_USERNAME / BOOMTAX_API_PASSWORD；这些版本 1 设置已过时。
• invalid_redirect_uri 注册错误需要使用受支持的回调主机，或由支持人员协助注册。切勿通过将凭据发送到其他主机来绕过此问题。
• 目录运行状况检查需要经过授权的测试连接。缺少测试配置文件时，即使 OAuth 发现可访问，也可能显示运行状况不佳的徽章。

开发

npm ci
npm test
npm run check
npm pack --dry-run

测试使用环回 OAuth/MCP 测试装置和合成数据，其中包括真实的 stdio 客户端进程。测试不会连接客户账户。发布前提条件和验证步骤请参阅发布和目录维护。

许可证

此仓库中的本地客户端源代码采用 MIT 许可证。访问托管的 BoomTax 服务仍受 BoomTax 服务条款和账户权限约束。