Chinese Nlp MCP server

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： （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 键。

工具

🔴 detectsensitivewords 不含任何内置词库

本工具不内置任何词库，也不内置任何示例词。词库唯一来源是调用方传入的

words 参数。传 [] 或 None 等同于不检测，直接返回

{"matches": [], "clean": true}。

内容安全策略必须由使用者自己掌控，工具不会替他预设。

你需要知道的行为细节

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

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

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

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

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

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

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

convertpinyin — tone2 的数字标在元音后**

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

segmentchinese — index 与 search 行为一致**

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

返回值怎么读

返回 dict 的工具（detectsensitivewords）会被 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。

Shortened. The full README is on GitHub.