Content
# cisp-mcp
`cisp-mcp` is a Python-written CISP API MCP service, used to encapsulate CISP enterprise information interfaces into MCP tools that can be called by large models.
The project uses `uv` to manage dependencies, based on the `mcp` Python SDK's `FastMCP` development, and accesses the backend API through the CISP AI gateway JSON interface.
## Project Capabilities
- Supports MCP clients such as Claude Code, Codex, Codex App, OpenClaw, and WorkBuddy.
- Each CISP product interface corresponds to an independent MCP tool, with the tool name containing the product number for easy troubleshooting and positioning.
- Automatically supplements `prodCode`, and the caller only needs to pass business parameters.
- Unifies and normalizes the return results of CISP, retaining the original return `raw_response`.
- Supports local smoke testing to verify whether the MCP service and tool registration are normal.
## Technology Stack
- Python `>=3.11`
- uv
- MCP Python SDK / FastMCP
- httpx
- python-dotenv
## Operating Environment Requirements
It is recommended to install the following on your local machine:
- Python `3.11` or higher
- uv
`uv` can manage Python versions; if your local machine does not have a compliant Python version, `uv` can automatically download and manage it in some environments. However, in enterprise intranets, proxies, or offline environments, automatic downloads may fail, so it is recommended to install Python `3.11+` in advance.
## Project Structure
```text
cisp-mcp/
├── src/cisp_mcp/
│ ├── server.py # MCP tool definition and service entry
│ ├── client.py # CISP JSON gateway client
│ ├── config.py # Environment variable configuration
│ └── interfaces.py # Product code, interface name, status code, etc. definitions
├── scripts/
│ └── smoke_test_mcp.py
├── docs/ # Local interface documentation directory
├── .env.example
├── pyproject.toml
└── README.md
```
## Quick Start
### 1. Download the Project
```bash
git clone <your-github-repo-url>
cd cisp-mcp
```
If you are in an existing directory:
```bash
cd /path/to/cisp-mcp
```
### 2. Check Python and uv
Check Python:
```bash
python3 --version
```
Check uv:
```bash
uv --version
```
If uv is not installed, you can install it according to the official uv method or use the existing Python environment on your local machine.
### 3. Install Dependencies
```bash
uv sync
```
### 4. Configure Environment Variables
Copy the template:
```bash
cp .env.example .env
```
Edit `.env`:
```text
CISP_ENDPOINT=https://cisp.zenitera.com
CISP_REQUEST_URI=/ectcispserver/api/entcreditapi/query
CISP_API_KEY=Replace with the real API Key
CISP_TIMEOUT_SECONDS=30
CISP_VERIFY_SSL=true
```
## Local Running and Debugging
### smoke test
This test only verifies whether the MCP service can start and whether the `tools/list` can see all tools, without calling the real CISP API or consuming interface times.
```bash
uv run python scripts/smoke_test_mcp.py
```
Normal results are similar to:
```text
Discovered MCP tools:
- p0010010_query_business_profile
- p0010058_query_business_basic_deep
...
- query_cisp_product
Total: 17
Smoke test passed.
```
### stdio Mode
stdio is a mode used by MCP clients such as Claude Code, Codex, and OpenClaw.
```bash
uv run cisp-mcp
```
When running manually, the terminal will stop, which is a normal phenomenon. stdio mode communicates with MCP clients through standard input/output and does not print access addresses like web services.
### HTTP Debugging Mode
If you want to use MCP Inspector for debugging, you can start Streamable HTTP:
```bash
uv run cisp-mcp --transport streamable-http
```
Default address:
```text
http://127.0.0.1:8000/mcp
```
Then start Inspector:
```bash
npx -y @modelcontextprotocol/inspector
```
Select in Inspector:
```text
Transport: Streamable HTTP
URL: http://127.0.0.1:8000/mcp
```
## Tool List
| Product Code | Interface Name | MCP tool |
| --- | --- | --- |
| `P0010010` | Enterprise Business Profile Query | `p0010010_query_business_profile` |
| `P0010058` | Enterprise Basic Information Query (Deep) | `p0010058_query_business_basic_deep` |
| `P0010068` | Enterprise Name Fuzzy Query (Simple) | `p0010068_fuzzy_search_company_name` |
| `P0010073` | Enterprise Trademark Information Query | `p0010073_query_trademark_info` |
| `P0010074` | Enterprise Software Copyright Information Query | `p0010074_query_software_copyright_info` |
| `P0010075` | Enterprise Work Copyright Information Query | `p0010075_query_work_copyright_info` |
| `P0010076` | Enterprise ICP Filing Information Query | `p0010076_query_icp_filing_info` |
| `P0010078` | Enterprise Patent Information Query | `p0010078_query_patent_info` |
| `P0010084` | Enterprise License Information Query | `p0010084_query_license_info` |
| `P0020021` | Enterprise Single Point Associated Information Query | `p0020021_query_single_point_related_info` |
| `P0050007` | Enterprise Public Opinion Information List Query | `p0050007_query_public_opinion_list` |
| `P0050008` | Enterprise Public Opinion Information Detail Query | `p0050008_query_public_opinion_detail` |
| `P0050007+P0050008` | Enterprise Public Opinion Information Query (List+Detail) | `p0050007_p0050008_query_public_opinion_info` |
| `P0060007` | Enterprise Business Two-Element Verification | `p0060007_verify_business_two_elements` |
| `P0060008` | Enterprise Business Three-Element Verification | `p0060008_verify_business_three_elements` |
| `P0110003` | Enterprise Honor Qualification Information Query | `p0110003_query_honor_qualification_info` |
| General | CISP JSON Gateway Debugging Query | `query_cisp_product` |
### Return Structure
Specialized tools will return normalized fields and raw responses:
- `product_code`: Product code
- `interface_name`: Interface name
- `success`: `resultCode == "00000"`
- `has_result`: Product status code is `4`
- `result_code_desc`: Result code description
- `product_status_desc`: Product status description
- `data`: Product data object
- `raw_response`: CISP original return
If the product data contains common list fields, additional shortcut fields will also be exposed, such as:
- `basicList`
- `fuzzyList`
- `brandList`
- `swList`
- `resultList`
- `icpList`
- `patentsList`
- `detailList`
- `entInvList`
- `infoList`
- `infoDetail`
- `matchList`
- `itemNameList`
## Invocation Examples
### Query Business Profile
```json
{
"ent_info": "Zhongtong Co., Ltd."
}
```
Corresponding tool:
```text
p0010010_query_business_profile
```
### Query Deep Business Information
```json
{
"ent_name": "Zhongtong Co., Ltd."
}
```
Corresponding tool:
```text
p0010058_query_business_basic_deep
```
### Query Patent Information
```json
{
"ent_info": "Zhongtong Co., Ltd.",
"page_no": "1",
"page_size": "10"
}
```
Corresponding tool:
```text
p0010078_query_patent_info
```
### Query Enterprise Investment and Appointment Association Information
Users only need to describe the query intention, and the model will choose the corresponding `relation_direction`:
- `"1"`: Query both investment and appointment relationships
- `"2"`: Query only investment relationships
- `"3"`: Query only appointment relationships
```json
{
"ent_info": "Zhongtong Co., Ltd.",
"relation_direction": "2"
}
```
Corresponding tool:
```text
p0020021_query_single_point_related_info
```
### Query Enterprise Honor Qualification
```json
{
"ent_info": "Zhongtong Co., Ltd."
}
```
Corresponding tool:
```text
p0110003_query_honor_qualification_info
```
### Query Enterprise License
```json
{
"ent_info": "Zhongtong Co., Ltd.",
"license_type": "ylxk",
"province": "Guangdong Province",
"page_no": "1",
"page_size": "10"
}
```
Corresponding tool:
```text
p0010084_query_license_info
```
### Query Enterprise Public Opinion Information
```json
{
"ent_name": ["Zhongtong Co., Ltd.", "Waterdrop Technology Service Co., Ltd."],
"page_no": "1",
"page_size": "10",
"max_details": 10
}
```
Corresponding tool:
```text
p0050007_p0050008_query_public_opinion_info
```
Note: This tool will first call `P0050007` to query the public opinion list, and then use the `entryId` returned by the list and the user's input `ent_name` to call `P0050008` to query the public opinion details.
### Query Only Enterprise Public Opinion List
```json
{
"ent_name": ["Zhongtong Co., Ltd.", "Waterdrop Technology Service Co., Ltd."],
"page_no": "1",
"page_size": "10"
}
```
Corresponding tool:
```text
p0050007_query_public_opinion_list
```
### Query Enterprise Public Opinion Details
```json
{
"entry_id": "Replace with the entryId returned by the public opinion list"
}
```
Corresponding tool:
```text
p0050008_query_public_opinion_detail
```
If only `ent_name` is passed, the service will first query the first page of public opinion list, and then take the first `entryId` to query details.
### Two-Element Verification
```json
{
"ent_name": "Zhongtong Co., Ltd.",
"reg_no": "Replace with the real unified social credit code"
}
```
Corresponding tool:
```text
p0060007_verify_business_two_elements
```
## Integrate into Claude Code
It is recommended to use stdio mode to let Claude Code automatically start the MCP service.
```bash
claude mcp add --transport stdio --scope user cisp-mcp -- uv --directory /path/to/cisp-mcp run cisp-mcp
```
Check configuration:
```bash
claude mcp list
claude mcp get cisp-mcp
```
Enter Claude Code and input:
```text
/mcp
```
After seeing `cisp-mcp` connected, you can use it.
Example questions:
```text
Query the business profile of Zhongtong Co., Ltd.
Query the patent information of Zhongtong Co., Ltd.
Help me quickly understand Zhongtong Co., Ltd. from business information, intellectual property, and website filing.
```
## Integrate into Codex CLI / Codex App
Codex CLI and Codex App use the same MCP configuration. It is recommended to add using the command:
```bash
codex mcp add cisp-mcp -- uv --directory /path/to/cisp-mcp run cisp-mcp
```
Check configuration:
```bash
codex mcp list
codex mcp get cisp-mcp
```
The configuration will be written to:
```text
~/.codex/config.toml
```
You can also manually configure:
```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
```
After configuration, reopen Codex App or create a new thread, and input in Codex:
```text
/mcp
```
Confirm that `cisp-mcp` is connected.
## Integrate into OpenClaw (Little Crayfish)
OpenClaw can save MCP Server definitions through `openclaw mcp set`. It is recommended to use stdio mode to let OpenClaw start `cisp-mcp` when needed.
### Local Project Method
First, ensure that the `.env` is configured in the project directory, and then execute:
```bash
openclaw mcp set cisp-mcp '{"command":"uv","args":["--directory","/path/to/cisp-mcp","run","cisp-mcp"]}'
```
Check configuration:
```bash
openclaw mcp list
openclaw mcp show cisp-mcp --json
```
If OpenClaw Gateway is already running, it is recommended to restart Gateway or create a new session after saving the MCP configuration:
```bash
openclaw gateway restart
```
### Directly Configure Environment Variables
If you do not want to rely on the `.env` in the project directory, you can also write the environment variables required for running to the OpenClaw MCP configuration:
```bash
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":"Fill in your real API Key","CISP_TIMEOUT_SECONDS":"30","CISP_VERIFY_SSL":"true"}}'
```
### Run Directly from GitHub
If you do not want to clone the project locally, you can use `uvx` to run from GitHub:
```bash
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":"Fill in your real API Key","CISP_TIMEOUT_SECONDS":"30","CISP_VERIFY_SSL":"true"}}'
```
After configuration, you can directly ask in OpenClaw:
```text
Query the business profile of Zhongtong Co., Ltd.
Query the public opinion information of Zhongtong Co., Ltd. and Waterdrop Technology Service Co., Ltd.
```
## Integrate into WorkBuddy
If WorkBuddy supports MCP stdio server, it is recommended to configure:
```json
{
"mcpServers": {
"cisp-mcp": {
"command": "uv",
"args": [
"--directory",
"/path/to/cisp-mcp",
"run",
"cisp-mcp"
]
}
}
}
```
If WorkBuddy only supports HTTP MCP, you can start it manually:
```bash
uv run cisp-mcp --transport streamable-http
```
Then configure in WorkBuddy:
```text
http://127.0.0.1:8000/mcp
```
It is recommended to use stdio first. stdio does not require a resident port, and the client will automatically start and manage the process.
## New Interface Development Process
If you need to add a new CISP product interface:
1. Place the PDF interface document in the local `docs/` directory.
2. Read the basic information, request parameters, return fields, and appendix status codes.
3. Add product definitions in `src/cisp_mcp/interfaces.py`.
4. Add a new `@mcp.tool()` in `src/cisp_mcp/server.py`.
5. The tool name format is recommended to be: `pproduct number_english semantic name`, such as `p0010010_query_business_profile`.
6. Update `EXPECTED_TOOLS` in `scripts/smoke_test_mcp.py`.
7. Run smoke test:
```bash
uv run python scripts/smoke_test_mcp.py
```
## Frequently Asked Questions
### 1. After manually running `uv run cisp-mcp`, the terminal does not move, is it stuck?
No. The default stdio mode waits for MCP clients to communicate through standard input/output. When running manually, it seems to be stuck. For debugging, use:
```bash
uv run cisp-mcp --transport streamable-http
```
### 2. What should I do if a certificate error occurs during a real call?
You can temporarily set:
```text
CISP_VERIFY_SSL=false
```
It is recommended to keep:
```text
CISP_VERIFY_SSL=true
```
in the production environment.
## Security Instructions
- Do not submit `.env`.
- Do not write API Key in code, README, or MCP client configuration.
- It is recommended to manage sensitive configurations through environment variables or `.env`.
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available