Cisp

cisp-mcp 是一个用 Python 编写的 CISP API MCP 服务，用于把 CISP 企业信息接口封装成可被大模型调用的 MCP tools。

项目使用 uv 管理依赖，基于 mcp Python SDK 的 FastMCP 开发，通过 CISP AI 网关 JSON 接口访问后端 API。

项目能力

• 支持 Claude Code、Codex、Codex App、OpenClaw、WorkBuddy 等 MCP 客户端接入。
• 每个 CISP 产品接口对应一个独立 MCP tool，工具名包含产品号，方便排查和定位。
• 自动补充 prodCode，调用方只需要传业务参数。
• 对 CISP 返回结果做统一归一化，保留原始返回 raw_response。
• 支持本地 smoke test，验证 MCP 服务和工具注册是否正常。

技术栈

• Python >=3.11
• uv
• MCP Python SDK / FastMCP
• httpx
• python-dotenv

运行环境要求

推荐本机提前安装：

• Python 3.11 或更高版本
• uv

uv 可以管理 Python 版本；如果本机没有符合要求的 Python，uv 在部分环境下可以自动下载和管理。但在企业内网、代理或离线环境中，自动下载可能失败，因此建议提前安装好 Python 3.11+。

项目结构

cisp-mcp/
├── src/cisp_mcp/
│   ├── server.py        # MCP tool 定义和服务入口
│   ├── client.py        # CISP JSON 网关客户端
│   ├── config.py        # 环境变量配置
│   └── interfaces.py    # 产品码、接口名称、状态码等定义
├── scripts/
│   └── smoke_test_mcp.py
├── docs/                # 本地接口文档目录
├── .env.example
├── pyproject.toml
└── README.md

快速开始

1. 下载项目

git clone <your-github-repo-url>
cd cisp-mcp

如果是在已有目录：

cd /path/to/cisp-mcp

2. 检查 Python 和 uv

检查 Python：

python3 --version

检查 uv：

uv --version

如果没有安装 uv，可以按 uv 官方方式安装，或使用本机已有的 Python 环境安装。

3. 安装依赖

uv sync

4. 配置环境变量

复制模板：

cp .env.example .env

编辑 .env：

CISP_ENDPOINT=https://cisp.zenitera.com
CISP_REQUEST_URI=/ectcispserver/api/entcreditapi/query
CISP_API_KEY=替换成真实 API Key
CISP_TIMEOUT_SECONDS=30
CISP_VERIFY_SSL=true

本地运行和调试

smoke test

这个测试只验证 MCP 服务能否启动、tools/list 是否能看到所有工具，不会调用真实 CISP API，也不会消耗接口次数。

uv run python scripts/smoke_test_mcp.py

正常结果类似：

Discovered MCP tools:
- p0010010_query_business_profile
- p0010058_query_business_basic_deep
...
- query_cisp_product
Total: 14
Smoke test passed.

stdio 模式

stdio 是给 Claude Code、Codex、OpenClaw、WorkBuddy 等 MCP 客户端使用的模式。

uv run cisp-mcp

手动执行时终端会停住，这是正常现象。stdio 模式通过标准输入/输出和 MCP 客户端通信，不会像 Web 服务一样打印访问地址。

HTTP 调试模式

如果要用 MCP Inspector 调试，可以启动 Streamable HTTP：

uv run cisp-mcp --transport streamable-http

默认地址：

http://127.0.0.1:8000/mcp

然后启动 Inspector：

npx -y @modelcontextprotocol/inspector

在 Inspector 中选择：

Transport: Streamable HTTP
URL: http://127.0.0.1:8000/mcp

工具列表

产品码	接口名称	MCP tool
P0010010	企业工商照面信息查询	p0010010_query_business_profile
P0010058	企业工商基本信息查询（深度）	p0010058_query_business_basic_deep
P0010068	企业名称模糊查询（简版）	p0010068_fuzzy_search_company_name
P0010073	企业商标信息查询	p0010073_query_trademark_info
P0010074	企业软件著作权信息查询	p0010074_query_software_copyright_info
P0010075	企业作品著作权信息查询	p0010075_query_work_copyright_info
P0010076	企业 ICP 备案信息查询	p0010076_query_icp_filing_info
P0010078	企业专利信息查询	p0010078_query_patent_info
P0050007	企业舆情信息列表查询	p0050007_query_public_opinion_list
P0050008	企业舆情信息详情查询	p0050008_query_public_opinion_detail
P0050007+P0050008	企业舆情信息查询（列表+详情）	p0050007_p0050008_query_public_opinion_info
P0060007	企业工商二要素验证	p0060007_verify_business_two_elements
P0060008	企业工商三要素验证	p0060008_verify_business_three_elements
通用	CISP JSON 网关调试查询	query_cisp_product

返回结构

专用工具会返回归一化字段和原始响应：

• product_code：产品码
• interface_name：接口名称
• success：resultCode == "00000"
• has_result：产品状态码为 4
• result_code_desc：结果码说明
• product_status_desc：产品状态说明
• data：产品数据对象
• raw_response：CISP 原始返回

如果产品数据里存在常用列表字段，也会额外透出快捷字段，例如：

• basicList
• fuzzyList
• brandList
• swList
• resultList
• icpList
• patentsList
• infoList
• infoDetail
• matchList

调用示例

查询工商照面信息

{
  "ent_info": "证通股份有限公司"
}

对应工具：

p0010010_query_business_profile

查询深度工商信息

{
  "ent_name": "证通股份有限公司"
}

对应工具：

p0010058_query_business_basic_deep

查询专利信息

{
  "ent_info": "证通股份有限公司",
  "page_no": "1",
  "page_size": "10"
}

对应工具：

p0010078_query_patent_info

查询企业舆情信息

{
  "ent_name": ["证通股份有限公司", "水滴科技服务有限公司"],
  "page_no": "1",
  "page_size": "10",
  "max_details": 10
}

对应工具：

p0050007_p0050008_query_public_opinion_info

说明：该工具会先调用 P0050007 查询舆情列表，再用列表返回的 entryId 和用户传入的 ent_name 调用 P0050008 查询舆情详情。

只查询企业舆情列表

{
  "ent_name": ["证通股份有限公司", "水滴科技服务有限公司"],
  "page_no": "1",
  "page_size": "10"
}

对应工具：

p0050007_query_public_opinion_list

查询企业舆情详情

{
  "entry_id": "替换成舆情列表返回的 entryId"
}

对应工具：

p0050008_query_public_opinion_detail

如果只传 ent_name，服务会先查询该企业第一页舆情列表，再取第一条 entryId 查询详情。

二要素验证

{
  "ent_name": "证通股份有限公司",
  "reg_no": "替换成真实统一社会信用代码"
}

对应工具：

p0060007_verify_business_two_elements

集成到 Claude Code

推荐使用 stdio 模式，让 Claude Code 自动启动 MCP 服务。

claude mcp add --transport stdio --scope user cisp-mcp -- uv --directory /path/to/cisp-mcp run cisp-mcp

检查配置：

claude mcp list
claude mcp get cisp-mcp

进入 Claude Code 后输入：

/mcp

看到 cisp-mcp connected 后即可使用。

示例问题：

查询一下证通股份有限公司的工商照面信息。

查询一下证通股份有限公司的专利信息。

帮我从工商信息、知识产权、网站备案几个角度快速了解证通股份有限公司。

集成到 Codex CLI / Codex App

Codex CLI 和 Codex App 使用同一份 MCP 配置。推荐用命令添加：

codex mcp add cisp-mcp -- uv --directory /path/to/cisp-mcp run cisp-mcp

检查配置：

codex mcp list
codex mcp get cisp-mcp

配置会写入：

~/.codex/config.toml

也可以手动配置：

[mcp_servers.cisp-mcp]
command = "uv"
args = ["--directory", "/path/to/cisp-mcp", "run", "cisp-mcp"]
startup_timeout_sec = 20
tool_timeout_sec = 120
enabled = true

配置后重新打开 Codex App，或新建一个 thread，在 Codex 中输入：

/mcp

确认 cisp-mcp 已连接。

集成到 OpenClaw（小龙虾）

OpenClaw 可以通过 openclaw mcp set 保存 MCP Server 定义。推荐使用 stdio 模式，让 OpenClaw 在需要时启动 cisp-mcp。

本地项目方式

先确保项目目录下已经配置好 .env，然后执行：

openclaw mcp set cisp-mcp '{"command":"uv","args":["--directory","/path/to/cisp-mcp","run","cisp-mcp"]}'

检查配置：

openclaw mcp list
openclaw mcp show cisp-mcp --json

如果 OpenClaw Gateway 已经在运行，保存 MCP 配置后建议重启 Gateway 或新建会话：

openclaw gateway restart

直接配置环境变量

如果不想依赖项目目录下的 .env，也可以把运行所需环境变量写入 OpenClaw MCP 配置：

openclaw mcp set cisp-mcp '{"command":"uv","args":["--directory","/path/to/cisp-mcp","run","cisp-mcp"],"env":{"CISP_ENDPOINT":"https://cisp.zenitera.com","CISP_REQUEST_URI":"/ectcispserver/api/entcreditapi/query","CISP_API_KEY":"填写自己的真实 API Key","CISP_TIMEOUT_SECONDS":"30","CISP_VERIFY_SSL":"true"}}'

直接从 GitHub 运行

如果不想本地 clone 项目，可以使用 uvx 从 GitHub 运行：

openclaw mcp set cisp-mcp '{"command":"uvx","args":["--from","git+https://github.com/fw-magic/cisp-mcp.git","cisp-mcp"],"env":{"CISP_ENDPOINT":"https://cisp.zenitera.com","CISP_REQUEST_URI":"/ectcispserver/api/entcreditapi/query","CISP_API_KEY":"填写自己的真实 API Key","CISP_TIMEOUT_SECONDS":"30","CISP_VERIFY_SSL":"true"}}'

配置完成后，可以在 OpenClaw 中直接提问：

查询一下证通股份有限公司的工商照面信息。

查询证通股份有限公司和水滴科技服务有限公司的舆情信息。

集成到 WorkBuddy

如果 WorkBuddy 支持 MCP stdio server，推荐配置：

{
  "mcpServers": {
    "cisp-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/cisp-mcp",
        "run",
        "cisp-mcp"
      ]
    }
  }
}

如果 WorkBuddy 只支持 HTTP MCP，可以先手动启动：

uv run cisp-mcp --transport streamable-http

然后在 WorkBuddy 中配置：

http://127.0.0.1:8000/mcp

建议优先使用 stdio。stdio 不需要常驻端口，客户端会自动启动和管理进程。

新增接口开发流程

后续如果要新增 CISP 产品接口：

1. 把 PDF 接口文档放到本地 docs/ 目录。
2. 阅读基本信息、请求参数、返回字段和附录状态码。
3. 在 src/cisp_mcp/interfaces.py 中新增产品定义。
4. 在 src/cisp_mcp/server.py 中新增一个 @mcp.tool()。
5. 工具名格式建议为：p产品号_英文语义名，例如 p0010010_query_business_profile。
6. 更新 scripts/smoke_test_mcp.py 的 EXPECTED_TOOLS。
7. 运行 smoke test：

uv run python scripts/smoke_test_mcp.py

常见问题

1. 手动运行 uv run cisp-mcp 后终端不动，是不是卡住了？

不是。默认 stdio 模式会等待 MCP 客户端通过标准输入/输出通信，手动运行时看起来像停住。调试时请用：

uv run cisp-mcp --transport streamable-http

2. 真实调用报证书错误怎么办？

本地联调时可以临时设置：

CISP_VERIFY_SSL=false

生产环境建议保持：

CISP_VERIFY_SSL=true

安全说明

• 不要提交 .env。
• 不要在代码、README、MCP 客户端配置里写死 API Key。
• 建议通过环境变量或 .env 管理敏感配置。