Content
<h1 align="center">ICPQuery-MCP</h1>
<p align="center">Based on <code>FastMCP</code> written ICP filing query MCP Server, support website, App, mini program, quick application filing information and illegal blacklist query</p>
<p align="center">
<img src="https://badgen.net/pypi/v/icpquery-mcp?label=PyPI&color=3775A9" alt="PyPI Version"/>
<img src="https://badgen.net/badge/Python/%3E%3D3.10/3776AB" alt="Python >=3.10"/>
<img src="https://badgen.net/badge/MCP%20SDK/%3E%3D1.28.1/6F42C1" alt="MCP SDK >=1.28.1"/>
<img src="https://badgen.net/pypi/dm/icpquery-mcp?label=Downloads&color=2EA44F&cache=86400" alt="PyPI Downloads"/>
<img src="https://badgen.net/github/license/helGayhub233/ICPQuery-MCP?label=License&color=blue" alt="License"/>
</p>
## Tool List
| Tool Name | Description |
| --- | --- |
| `icp_query` | Query ICP filing information, support `web/app/mapp/kapp` |
| `icp_blacklist` | Query illegal blacklist, support `bweb/bapp/bmapp/bkapp` |
| `config_show` | View current running configuration |
| `check_environment` | Check running environment, dependencies and support types |
## Supported Types
| Type | Capability |
| --- | --- |
| Website Filing | Domain name, subject name, filing number and other keyword queries |
| App Filing | App name, subject name and other keyword queries, and automatically supplement details |
| Mini Program Filing | Mini program name, subject name and other keyword queries, and automatically supplement details |
| Quick Application Filing | Quick application name, subject name and other keyword queries, and automatically supplement details |
| Illegal Blacklist | Website, App, mini program, quick application blacklist query |
## Quick Start
### Run from Source
Requires Python `>=3.10`, MCP Python SDK `>=1.28.1`.
```bash
cd ICPQuery-MCP
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
icpquery-mcp
```
### MCP Configuration
Recommended to run in MCP client with fixed project directory:
```json
{
"mcpServers": {
"icp-query": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/ICPQuery-MCP",
"run",
"icpquery-mcp"
],
"env": {
"ICP_RATE_LIMIT_QUERY_PER_MIN": "5",
"ICP_RATE_LIMIT_BLACKLIST_PER_MIN": "3",
"ICP_PROXY_TUNNEL": ""
}
}
}
}
```
If already installed in virtual environment, can directly use entry command:
```json
{
"mcpServers": {
"icp-query": {
"command": "icpquery-mcp",
"args": []
}
}
}
```
## Local CLI
```bash
icpquery check-env
icpquery config-show
icpquery query baidu.com
icpquery query 微信 -t app
icpquery query baidu.com -t bweb
```
## Environment Variables
Environment variables use `ICP_` prefix naming convention.
| Environment Variable | Description |
| --- | --- |
| `ICP_TIMEOUT` | HTTP request timeout seconds, default `30` |
| `ICP_CONCURRENCY` | Detail completion concurrency, internally unified to `1` |
| `ICP_RATE_LIMIT_ENABLED` | Whether to enable MCP tool frequency limit, default `true` |
| `ICP_RATE_LIMIT_QUERY_PER_MIN` | `icp_query` allowed times per minute, default `5` |
| `ICP_RATE_LIMIT_BLACKLIST_PER_MIN` | `icp_blacklist` allowed times per minute, default `3` |
| `ICP_RATE_LIMIT_MAX_CONCURRENT` | Query tool maximum concurrency, internally unified to `1` |
| `ICP_PROXY_TUNNEL` | Fixed proxy address, e.g. `socks5://127.0.0.1:1080` |
| `ICP_PROXY_POOL_URL` | Proxy pool API address, currently reserved configuration |
| `ICP_PROXY_POOL_SIZE` | Proxy pool size, currently reserved configuration |
| `ICP_PROXY_POOL_IPV6` | Local IPv6 export rotation switch, currently reserved configuration |
Default configuration see `config.example.yml`.
## Query Parameters
### `icp_query`
| Parameter | Description |
| --- | --- |
| `name` | Query keyword, support company name, domain name, filing number, App name, etc. |
| `type` | Query type: `web`, `app`, `mapp`, `kapp`, default `web` |
| `page` | Page number, default `1` |
| `page_size` | Number per page, maximum `26` |
| `proxy` | Single request proxy, priority higher than `ICP_PROXY_TUNNEL` |
### `icp_blacklist`
| Parameter | Description |
| --- | --- |
| `name` | Query keyword, support domain name, App name, etc. |
| `type` | Blacklist type: `bweb`, `bapp`, `bmapp`, `bkapp`, default `bweb` |
| `proxy` | Single request proxy, priority higher than `ICP_PROXY_TUNNEL` |
## Request Limit
Project will do local protection in MCP service process to avoid client concurrent requests directly hitting target interface.
| Tool | Control Method |
| --- | --- |
| `icp_query` | Singleton queue execution, default 5 times per minute |
| `icp_blacklist` | Singleton queue execution, default 3 times per minute |
| App/mini program/quick application detail completion | Serial execution |
Qoder and other MCP clients may default to trigger 5/10 tool calls concurrently; this project internally forces serialization, and the next query will access the target interface only after the previous query is complete.
## Project Structure
```text
src/
icpquery_mcp/
server.py # MCP entry
cli.py # Local CLI
core/
client.py # Industry and Commerce Bureau interface call, token, verification code and detail completion
captcha.py # Slider verification code offset recognition
config.py # YAML and environment variable configuration
ratelimit.py # Frequency control and singleton queue protection
tools/
local_tools.py # MCP tool and CLI reuse encapsulation
```
## Manual Verification
```bash
python -m compileall src
icpquery check-env
icpquery config-show
```
## Precautions
**This project is only for learning and technical research, strictly prohibited for any commercial or illegal purposes.**
Please use within the scope of legitimate authorization and bear the risk of failure caused by interface changes, verification code strategy changes, target risk control or network environment.
## License
MIT License, see `LICENSE`.
