io.github.leonmch-byte/chinese-nlp-mcp

chinese-nlp-mcp

mcp-name: io.github.leonmch-byte/chinese-nlp-mcp

中文 NLP 能力的 MCP Server：分词、关键词提取、拼音转换、自定义敏感词检测。 本地 stdio 运行，全部推理在进程内完成。

📝 Tutorial: How to Add Chinese NLP to Your AI Agent in 5 Minutes

特性

• 纯本地推理 — 未配置 license key 时零网络请求、无遥测，文本不离开本机
• stdio transport — 本地进程通信，不开放任何端口
• 协议干净 — 日志一律走 stderr，不污染 stdout 的 JSON-RPC 流

环境要求

Python 3.10 或更高版本。

安装

方式一：uvx 一键运行（推荐，无需安装）

uvx chinese-nlp-mcp

需要先安装 uv：https://docs.astral.sh/uv/getting-started/installation/ （macOS/Linux 用 curl -LsSf https://astral.sh/uv/install.sh | sh， Windows 用 irm https://astral.sh/uv/install.ps1 | iex）

方式二：pip 安装

pip install chinese-nlp-mcp
# 安装后同样可用命令行启动
chinese-nlp-mcp

方式三：从源码安装（备选，开发用）

git clone https://github.com/leonmch-byte/chinese-nlp-mcp
cd chinese-nlp-mcp

# Windows (Git Bash)
python -m venv .venv
./.venv/Scripts/python.exe -m pip install -r requirements.txt

# macOS / Linux
python3 -m venv .venv
./.venv/bin/python -m pip install -r requirements.txt

客户端接入

推荐用 uvx，无需关心 Python 环境：

{
  "mcpServers": {
    "chinese-nlp-mcp": {
      "command": "uvx",
      "args": ["chinese-nlp-mcp"]
    }
  }
}

若用 pip 安装（方式二）：

{
  "mcpServers": {
    "chinese-nlp-mcp": {
      "command": "chinese-nlp-mcp"
    }
  }
}

若从源码安装（方式三）：

{
  "mcpServers": {
    "chinese-nlp-mcp": {
      "command": "/absolute/path/to/chinese-nlp-mcp/.venv/Scripts/python.exe",
      "args": ["/absolute/path/to/chinese-nlp-mcp/server.py"]
    }
  }
}

VS Code 用 servers 键，Claude Desktop / Cursor 用 mcpServers 键。

工具

🔴 detect_sensitive_words 不含任何内置词库

本工具不内置任何词库，也不内置任何示例词。词库唯一来源是调用方传入的 words 参数。传 [] 或 None 等同于不检测，直接返回 {"matches": [], "clean": true}。 内容安全策略必须由使用者自己掌控，工具不会替他预设。

你需要知道的行为细节

这些直接影响你怎么解析返回值，所以列在这里。

detect_sensitive_words — 重叠匹配返回全部命中

不去重、不做最长/最短优先裁剪。调用方是自己词库的负责人， 最清楚"命中什么"才是关心的信号；拿到全部命中后可按 index 自行裁剪或聚合。

例：text="中华人民共和国", words=["中国人民","人民"] → 返回 2 条命中， index 分别为 0 和 2。index 是字符索引（中文按 1 字计，非字节索引）。

extract_keywords — weight 是未归一化的 TF-IDF 原始分

值域通常 0 ~ 6，可大于 1.0（例："天安门广场" → 1.6316）。 它表示该词在当前语料中的重要程度，不是概率或百分比。

返回顺序已按权重降序；topN 超过可提取词数时返回全部词，不报错。 中英混合文本中，英文单词会作为独立 token 保留并参与计算，不会被过滤 （例：Python 编程语言很强大 → 提取出 Python，weight 3.98）。

convert_pinyin — tone2 的数字标在元音后

zhong → zho1ng，不是 zhong1。这是 pypinyin 的既有命名规则。 style 只接受上表四个值，传入其他值会抛错（底层库本会静默降级， 本项目在入口处拦下，避免你拿到"看起来对但不是你要的结果"）。

segment_chinese — index 与 search 行为一致

jieba 没有独立的 index 模式，本项目把 index 映射为搜索模式。 两种模式都不返回位置信息，返回值统一是 list[str]。

返回值怎么读

返回 dict 的工具（detect_sensitive_words）会被 fastmcp 直接展开为 structuredContent，不额外加 result 包装层； 返回 list / str 的工具则会被包成 structuredContent.result。

例：从 structuredContent.matches 与 structuredContent.clean 取值， 而不是 structuredContent.result.matches。

错误处理

参数非法抛 ValueError，内部失败抛 RuntimeError， 均由 fastmcp 转成 isError=true，工具签名保持纯净。

免费层每日配额（v0.2.0 起）

所有工具都可免费使用，但有每日次数上限（按 UTC 00:00 重置）：

单次输入上限：文本 20,000 字符、自定义词库 1,000 条、topN 最大 50。

达到上限时该工具返回 isError: true，并附带当前限制、重置时间、 Pro 权益与升级链接。hello_world 始终不受影响，避免客户端误判服务器故障。

Pro License（v0.3.0 起）

export CHINESE_NLP_LICENSE_KEY=<你的 key>   # Windows: $env:CHINESE_NLP_LICENSE_KEY="..."

如果你希望免去每次配环境变量，可显式同意把 key 存在本地 （权限 0600 + HMAC 签名）：

export CHINESE_NLP_STORE_KEY=1

诊断用 CHINESE_NLP_LICENSE_DEBUG=1（tier 与缓存状态打到 stderr）， 自解锁用 CHINESE_NLP_LICENSE_RESET=1（清除本地缓存与凭证）。

License 失效是静默的：不会弹窗、不会改变工具返回结构， 只是退回免费层配额（表现为原有的配额超限文案）。

每日计数保存在你本机的状态文件里：

• Windows: %LOCALAPPDATA%\chinese-nlp-mcp\
• macOS: ~/Library/Application Support/chinese-nlp-mcp/
• Linux: $XDG_STATE_HOME/chinese-nlp-mcp/

需要更高额度与批量 API：https://wolfmanchao.gumroad.com/l/chinese-nlp-mcp-pro （$19 买断，非订阅）

Privacy

Without a license key: Fully offline. No network calls, no telemetry. Your text never leaves the machine.

With a Pro license key: The key is verified against Gumroad once at startup, cached for 24 hours. Only product_id and license_key are sent. No text content, no usage statistics, no machine identifiers.

Verification can be disabled entirely by not setting CHINESE_NLP_LICENSE_KEY.

工具调用本身在两种情况下都完全离线 —— 网络请求只发生在服务器启动时， 且仅在配置了 license key 时。每 24 小时至多一次。

本地只保存 license key 的 SHA-256 摘要（前 16 位十六进制）， 不保存明文。缓存、日志、错误信息中都不含明文 key、邮箱或 IP。

这个项目是 MIT 开源的本地软件，没有 DRM。 每日计数是防篡改（tamper-resistant）而非防破解（tamper-proof）—— 有决心的人总能从源码层面绕过任何本地机制。 我们卖的是便利（批量 API、长文本、自定义词典），不是锁。

开发

验收方式、测试规约、实现层踩坑记录见 DEVELOPMENT.md。

License

MIT