beian-mcp-server

中国备案信息查询 MCP 服务端。通过 MCP 协议提供工具接口，支持工信部 ICP 备案查询，可同时运行于 HTTP（Streamable HTTP） 与 stdio 两种传输模式。

功能特性

• ICP 备案查询：通过 MCP 工具 query-icp 查询中国大陆工信部 ICP 备案信息，支持按域名、单位名称、APP 名称等关键词检索，覆盖网站 / 移动应用 / 小程序 / 快应用等服务类型。

• 双传输模式：通过环境变量 MCP_TRANSPORT 一键切换 HTTP 与 stdio 模式，适配不同的 MCP 客户端接入方式。

• 单文件构建 + 混淆：esbuild 打包为单一 dist/index.cjs（CJS 格式），支持 javascript-obfuscator 混淆，便于分发部署。

• 无状态请求处理：HTTP 模式下每次请求通过 McpServerFactory 创建独立 server 实例，规避单例 connect 冲突，并兼容 2025 时代客户端的无状态回退。

Related MCP server: whois-mcp

技术栈

目录结构

beian_mcp/
├── src/
│   ├── index.ts            # 入口：注册工具、启动 HTTP / stdio 服务
│   ├── module/
│   │   └── icp.ts          # 工信部 ICP 备案查询核心业务（含滑块验证码识别流程）
│   ├── api/
│   │   └── icp.ts          # ICP 查询上游网页接口封装
│   ├── utils/
│   │   ├── captcha.ts      # 滑块验证码识别（colorBlockSlider，基于 sharp）
│   │   ├── crypto.ts       # 加解密工具
│   │   └── internet.ts     # 网络请求工具
│   ├── tests/
│   │   └── module/
│   │       └── icp.test.ts # ICP 流程测试用例
│   └── types/
│       └── icp.ts          # 备案查询类型定义与 ServiceType 枚举
├── scripts/
│   ├── build.mjs           # 构建脚本：清空 dist → esbuild 打包 → 混淆
│   └── obfuscate.mjs       # 混淆脚本（支持 .cjs）
├── dist/                   # 构建产物（index.cjs）
├── package.json
└── tsconfig.json

环境要求

• Node.js ≥ 18（推荐 20+）

• pnpm ≥ 11（项目通过 devEngines 锁定，npx 可能存在兼容问题，请使用 pnpm）

• sharp 为原生模块，运行时需保留在 node_modules 中（构建时已通过 --external:sharp 排除）

快速开始

# 1. 安装依赖
pnpm install

# 2. 开发模式（tsx 热运行，HTTP 模式）
pnpm dev

运行

服务启动模式由环境变量 MCP_TRANSPORT 控制：

HTTP 模式（默认）

# 使用默认端口 3000
node dist/index.cjs

# 自定义端口
$env:PORT = 8080; node dist/index.cjs

启动后端点地址：http://127.0.0.1:3000/mcp，按下方「MCP 客户端配置」的 HTTP 示例接入。

stdio 模式

$env:MCP_TRANSPORT = "stdio"; node dist/index.cjs

按下方「MCP 客户端配置」的 stdio 示例接入。

MCP 客户端配置

将下方 JSON 片段合并到你使用的 MCP 客户端（Claude Desktop / Cline / Cursor 等）的 mcpServers 配置中。各客户端字段定义一致，仅配置文件位置不同（如 Claude Desktop 的 claude_desktop_config.json、Cline 的扩展设置）。

HTTP 模式（远程接入）

先在本地启动服务（node dist/index.cjs），再配置：

{
  "mcpServers": {
    "beian-mcp-server": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {}
    }
  }
}

stdio 模式（本地进程）

使用构建产物 dist/index.cjs：

{
  "mcpServers": {
    "beian-mcp-server": {
      "command": "node",
      "args": ["E:\\Project\\Web\\beian_mcp\\dist\\index.cjs"],
      "env": { "MCP_TRANSPORT": "stdio" }
    }
  }
}

开发调试时使用 tsx 直跑源码：

{
  "mcpServers": {
    "beian-mcp-server": {
      "command": "pnpm",
      "args": ["exec", "tsx", "src/index.ts"],
      "env": { "MCP_TRANSPORT": "stdio" }
    }
  }
}

注意：stdio 模式必须在 env 中设置 MCP_TRANSPORT=stdio，否则服务会以默认的 HTTP 模式启动并监听端口，客户端将无法通信。

接入成功后，客户端 tools/list 应能列出 query-icp 工具，即可开始查询备案信息。

构建

# 完整构建：单文件打包 + 混淆（产出 dist/index.cjs，混淆后约 5MB）
pnpm build

# 仅单文件打包、不做混淆（便于排查产物问题）
pnpm build:raw

构建链路说明：

1. scripts/build.mjs 清空 dist 目录；

2. esbuild 打包为 CJS 单文件 dist/index.cjs（--format=cjs、--external:sharp 保留原生模块、--alias:@=./src 解析路径别名）；

3. scripts/obfuscate.mjs 对产物执行混淆（--raw 时跳过此步）。

说明：产物使用 .cjs 扩展名输出，以规避 package.json 中 "type": "module" 导致的 ESM 解析问题（ESM 单文件下 express 依赖的动态 require("tty") 不被支持）。

测试

# 运行一次测试
pnpm test

# 监听模式
pnpm test:watch

MCP 工具

query-icp

查询中国大陆工信部 ICP 备案信息。

返回结果为 JSON 文本，包含备案主体、许可证号、网站信息等。

已知限制

• 公安备案查询暂不支持：query-police 工具当前未实现（公安备案查询的验证码识别本地化方案尚未落地）。

• ICP 查询依赖第三方网页接口，若上游接口变更或触发WAF风控，查询可能失败并返回 [ICP 查询失败] 错误信息。

许可

CC BY-NC-SA 4.0