mcpField
H
humanpen-mcp

humanpen-mcp

本地服务
github.com/humanpen生产力45 天前更新
代码仓库

关于 humanpen-mcp

humanpen-mcp 是用于编辑 .docx 和 .pptx 文档的 MCP 服务，面向学术及专业写作者。它可根据检测报告定位标记段落，同时保留文档结构和格式。

主要功能

  1. 01改写整篇文档或选定段落
  2. 02定位检测报告标记的文本
  3. 03保留格式、引文和公式
  4. 04支持 12 种引文格式转换
  5. 05压缩和翻译文档

适用场景

  1. 01仅修改 Turnitin 报告标记的段落
  2. 02将引文和参考文献转换为其他格式
  3. 03翻译或缩短可编辑文档

MCP 相关

它通过 `humanpen-mcp` 和 `HUMANPEN_API_KEY` 作为 stdio MCP 服务运行。它向 MCP 客户端提供文档编辑、引文处理、翻译、报告读取、任务状态和额度查询工具。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "humanpen-humanpen": {
      "command": "npx",
      "args": [
        "-y",
        "humanpen-mcp"
      ],
      "env": {
        "HUMANPEN_API_KEY": "<HUMANPEN_API_KEY>"
      }
    }
  }
}
启动命令npx -y humanpen-mcp
需要配置的环境变量
HUMANPEN_API_KEY密钥HumanPen API key. Create one at https://humanpen.net/settings/api-keys

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
npmhumanpen-mcp1.4.4

工具

8

收录的工具列表 · 更新于 4 天前

参数类型必填说明
segmentsarray否按段落控制词数（可选）：每项包含一个被标记的段落及其 min_words/max_words。通过 read_detection_report 获取段落文本，并同时传入 report_path，以便由报告界定范围。此功能为实验性功能，与 min_words 具有相同注意事项。不能与整篇文档的 min_words/max_words 同时使用。
strategyenum否改写强度；通常首次选择 balanced，aggressive 的改写幅度更大balanced | aggressive
max_wordsinteger否改写文档的词数上限（可选；不设限制时省略）。与 min_words 具有相同的实验性注意事项和互斥限制。
min_wordsinteger否改写文档的词数下限（可选；不设限制时省略）。实验性功能——词数限制会明显削弱降低 AI 率的效果，因此除非用户要求控制篇幅，否则请省略。不能与 report_path 或 segments 同时使用。
output_pathstring否结果的写入位置；默认写入源文件所在目录
report_pathstring否Turnitin/iThenticate AI 报告 PDF 的路径；仅重写其中标记的段落
instructionsstring否此任务的额外要求
wait_secondsnumber否返回任务 ID 前的等待时长（默认 55 秒）
document_pathstring是要重写的 .docx 或 .pptx 的绝对路径

详细介绍

humanpen-mcp

License MCP Node

English · 简体中文 · 日本語

网站 · 定价 · 开发者文档

关键词： AI 文本润色器、MCP 服务、Model Context Protocol、Turnitin AI 检测、降低 AI 评分、AI 文本润色、绕过 AI 检测、DOCX AI 文本润色器、AI 内容改写器、AI 写作工具、Claude MCP、Cursor MCP、iThenticate AI 报告

润色被标记的内容。保留其余部分。 这是一个适用于 HumanPen 的 MCP 服务——一款文档级 AI 文本润色器，可润色整份文档、改写用户选定的段落，或自动定位 Turnitin / iThenticate AI 检测报告中标记的文本。它能直接编辑 .docx / .pptx 文件，同时保留格式、表格、图片、引文和公式。还支持在 12 种格式间转换引文、按字数限制精简内容，以及在 12 种语言间翻译。

claude mcp add humanpen -s user -e HUMANPEN_API_KEY=hp_your_key -- npx -y humanpen-mcp

功能

  • 根据检测报告选择性改写——导入 Turnitin / iThenticate AI 写作报告，精准定位标记的段落；未标记的内容绝不会改动
  • 输入输出格式一致——DOCX 文件处理后仍为 DOCX，PPTX 文件处理后仍为 PPTX；格式、表格、图片和公式完整保留，结果仍可编辑
  • 保留学术结构——文内引文、参考文献列表、脚注、目录字段、交叉引用、图表编号、公式和特殊格式均作为受保护对象处理
  • 不注入错误——通过重组含义和句法来改变表达；绝不以添加语法错误、拼写错误或别扭句子作为检测策略
  • 支持完整长度的文档——输入字数不限；单个文件最大可达 100 MB，无需拆分到文本框中
  • 可免费继续处理——仍被标记？可免费重新润色，并生成新报告，直到 AI 比率降至 * 或 0%
  • 字数控制（实验性）——设置最少/最多字数范围，使输出保持在目标长度内
  • 按改写量付费——按实际改动的字数计费，而非整份文档；失败和取消的任务不收费；额度永不过期

获取密钥

在 https://humanpen.net 注册，并在 https://humanpen.net/settings/api-keys 创建密钥。新账号会获得免费额度， 足以处理一份文档并查看结果。

密钥应存放在环境变量中，绝不要放在 URL 里。URL 会留在服务端 日志、代理日志、Shell 历史记录和屏幕截图中。

安装

Claude Code 
claude mcp add humanpen -s user -e HUMANPEN_API_KEY=hp_your_key -- npx -y humanpen-mcp

-s user 会将其应用于每个项目。默认作用范围是 local，只会在你运行命令的目录中加载服务——因此，首次在其他位置打开 Claude Code 时，看起来就像安装出了问题。

如果你的版本不接受 -e（上游问题报告），请使用 JSON 格式：

claude mcp add-json humanpen -s user '{"command":"npx","args":["-y","humanpen-mcp"],"env":{"HUMANPEN_API_KEY":"hp_your_key"}}'
OpenAI Codex

在 ~/.codex/config.toml 中：

[mcp_servers.humanpen]
command = "npx"
args = ["-y", "humanpen-mcp"]
env = { HUMANPEN_API_KEY = "hp_your_key" }
CodeBuddy / WorkBuddy 
codebuddy mcp add --scope user humanpen -- npx -y humanpen-mcp

它也会读取配置中的 ${VAR}，因此密钥可以保存在环境变量中，而不是写入文件：

{ "mcpServers": { "humanpen": {
  "command": "npx", "args": ["-y", "humanpen-mcp"],
  "env": { "HUMANPEN_API_KEY": "${HUMANPEN_API_KEY}" }
} } }

~/.codebuddy/.mcp.json 适用于每个项目，<project>/.mcp.json 适用于单个项目。

Gemini CLI

它提供 gemini mcp add，但不同版本的参数顺序不同——运行 gemini mcp add --help，并按照它显示的用法操作。使用 -e HUMANPEN_API_KEY=... 传入密钥，并使用 -s user 设置作用范围；默认值是 project，仅适用于你运行命令的目录。

Claude Desktop

在 claude_desktop_config.json 中。请使用 npx 的绝对路径——运行 which npx 并粘贴结果：桌面应用由操作系统启动，使用的 PATH 很精简，因此在终端中有效的裸名称在这里通常无法找到，而唯一的表现就是工具始终不会出现。

{
  "mcpServers": {
    "humanpen": {
      "command": "npx",
      "args": ["-y", "humanpen-mcp"],
      "env": { "HUMANPEN_API_KEY": "hp_your_key" }
    }
  }
}
Cursor / Windsurf / Cline

三者读取的格式相同——Cursor 使用 .cursor/mcp.json，Windsurf 使用 ~/.codeium/windsurf/mcp_config.json，Cline 使用其 MCP 设置面板：

{
  "mcpServers": {
    "humanpen": {
      "command": "npx",
      "args": ["-y", "humanpen-mcp"],
      "env": { "HUMANPEN_API_KEY": "hp_your_key" }
    }
  }
}
OpenCode

在 opencode.json 中——键名与其他客户端略有不同：

{
  "mcp": {
    "humanpen": {
      "type": "local",
      "command": ["npx", "-y", "humanpen-mcp"],
      "environment": { "HUMANPEN_API_KEY": "hp_your_key" }
    }
  }
}
VS Code — 密钥不会写入配置文件 
{
  "mcp": {
    "inputs": [
      { "type": "promptString", "id": "humanpenKey", "description": "HumanPen API key", "password": true }
    ],
    "servers": {
      "humanpen": {
        "command": "npx",
        "args": ["-y", "humanpen-mcp"],
        "env": { "HUMANPEN_API_KEY": "${input:humanpenKey}" }
      }
    }
  }
}

VS Code 会提示输入一次密钥，并将其存储在密钥库中，因此不会将密钥写入你可能提交的文件。

从源代码安装，或在 npm 发布之前安装 
git clone https://github.com/humanpen/humanpen-mcp
cd humanpen-mcp && npm install && npm run build

然后将客户端指向 node /path/to/humanpen-mcp/dist/index.js，而不是 npx -y humanpen-mcp。

任何 MCP 客户端都可以使用：这是一个普通的 stdio 服务，由 npx -y humanpen-mcp 启动，并在其环境中设置 HUMANPEN_API_KEY。

工具

工具功能积分
humanize_document改写 .docx/.pptx，使其读起来像是由人撰写，并降低 AI 检测器的评分。也可以选择提供检测报告，仅改写其中标记的段落。可将全文长度控制在指定的字数范围内，或将各段长度控制在各自的字数范围内（实验性功能——限制字数会削弱降低 AI 率的效果）。是
free_rehumanize免费继续处理已完成的 humanize_document 任务：为其结果上传一份新的检测报告，仅改写仍被标记的段落。每个任务限用一次，并设有每日上限；报告必须与该结果相匹配。免费
fix_citations将文内引用和参考文献列表转换为 APA 7、MLA 9、Harvard、Chicago、IEEE、Vancouver、GB/T 7714、AMA、ACS 或 OSCOLA 格式。不改动正文。是
condense_document将 .docx 缩短至指定字数，同时保留结构和引用。是
translate_document在 12 种语言之间翻译 .docx/.pdf/.pptx/.xlsx/.epub/.html/.txt，同时保留版式。是
read_detection_report读取 Turnitin 或 iThenticate AI Writing 报告：总体 AI 百分比及标记的段落。免费
check_job查询任务并下载其结果。免费
get_credit_balance查看剩余积分。免费

两件值得了解的事

任务需要几分钟；工具调用不需要。 每次操作会等待约 55 秒——足以处理大多数文档——然后返回一个 job_id，并提示调用 check_job。无论如何，工作都会在服务端继续进行；工具提前返回不会丢失任何内容。

ai_percent 可能为 null，这通常是个好消息。 只要 AI 写作比例低于 20%，Turnitin 就会打印 * 而非数字——它不会量化这个区间，因为误报太多。因此，null 表示“低于 20%，Turnitin 不会提供更多信息”，绝不表示“0%”，也不表示“没有结果”。

常见问题

这能降低 Turnitin 的 AI 评分吗？ 使用 balanced 模式时，通常一次处理就能将评分降至 20% 以下——这是 Turnitin 打印 * 而非数字的阈值。如果未能达到，可将结果连同新报告一起提交；只有仍被标记的段落才会重写。

也适用于 iThenticate 吗？ 是的——可以提交任一种报告。系统会根据文件读取格式。

我的文档会发送给模型吗？ 不会。系统会上传文件并返回路径。一篇 40 页的论文不会消耗任何令牌。

隐私政策

传递给工具的文档会通过 HTTPS 上传至 HumanPen 的 API（api.humanpen.net）进行处理；结果会写回你的磁盘，处理后的文件会在服务端保留约 7 天，以便 check_job 和免费的再次人性化处理能够找到这些文件。文档内容绝不会进入模型上下文。完整政策——包括收集哪些信息、保留期限以及如何联系我们——请见 https://humanpen.net/legal/privacy。

开发

npm install
npm run build
HUMANPEN_API_KEY=hp_... node selftest.mjs sample.docx report.pdf

selftest.mjs 会启动构建好的服务，并像真正的客户端一样通过 stdio 与其进行 JSON-RPC 通信，以验证协议、工具注册、stdout 规范以及一个端到端任务，而不只是验证函数能否返回结果。它需要有效密钥并会消耗额度，因此属于发布前检查，而非 CI 步骤。

链接

Apache-2.0

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。