{
  "markdown": "# humanpen-mcp\n\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n[![MCP](https://img.shields.io/badge/Model_Context_Protocol-stdio-000000.svg)](https://modelcontextprotocol.io)\n[![Node](https://img.shields.io/badge/node-%3E%3D18-339933.svg)](https://nodejs.org)\n\nEnglish · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)\n\n[Website](https://humanpen.net) · [Pricing](https://humanpen.net/pricing) · [Developer docs](https://humanpen.net/developers)\n\n> **Keywords:** ai humanizer, mcp server, model context protocol, turnitin ai detection, reduce ai score, humanize ai text, bypass ai detection, docx ai humanizer, ai content rewriter, ai writing tool, claude mcp, cursor mcp, ithenticate ai report\n\n**Humanize what's flagged. Preserve the rest.** An MCP server for [HumanPen](https://humanpen.net) — a document-level AI humanizer that can humanize an entire document, rewrite user-selected passages, or automatically target flagged text from a Turnitin / iThenticate AI-detection report, editing `.docx` / `.pptx` files in place while preserving formatting, tables, images, citations, and formulas. Also converts citations between 12 styles, condenses to a word budget, and translates between 12 languages.\n\n```bash\nclaude mcp add humanpen -s user -e HUMANPEN_API_KEY=hp_your_key -- npx -y humanpen-mcp\n```\n\n## Features\n\n- **Selective rewriting by detection report** — import a Turnitin / iThenticate AI Writing Report to pinpoint flagged passages; unflagged content is never touched\n- **Format in, format out** — a DOCX comes back as a DOCX, a PPTX as a PPTX; formatting, tables, images, and formulas survive intact and the result is still editable\n- **Academic structure preserved** — in-text citations, reference lists, footnotes, TOC fields, cross-references, figure numbering, equations, and special formatting are treated as protected objects\n- **No error injection** — restructures meaning and syntax to change expression; never adds grammar mistakes, spelling errors, or awkward sentences as a detection strategy\n- **Full-length documents** — no per-input word limit; a single file can be up to 100 MB, no splitting into text boxes\n- **Free to keep going** — still flagged? Re-humanize for free with a fresh report until the AI rate falls to `*` or 0%\n- **Word-count control (experimental)** — set a min/max word range to keep the output within a target length\n- **Pay per rewrite** — billed on words actually changed, not the whole document; failed and cancelled jobs cost nothing; credits never expire\n\n## Get a key\n\nSign up at <https://humanpen.net> and create a key at\n<https://humanpen.net/settings/api-keys>. New accounts start with free credits,\nenough to put a document through and see what comes back.\n\nThe key goes in an environment variable, never in a URL. URLs end up in server\nlogs, proxy logs, shell history and screenshots.\n\n## Install\n\n<details open>\n<summary><b>Claude Code</b></summary>\n\n```bash\nclaude mcp add humanpen -s user -e HUMANPEN_API_KEY=hp_your_key -- npx -y humanpen-mcp\n```\n\n`-s user` puts it in every project. The default scope is `local`, which\nloads the server only in the directory you ran the command from — and looks\nlike a broken install the first time you open Claude Code somewhere else.\n\nIf your version rejects `-e` ([reported\nupstream](https://github.com/anthropics/claude-code/issues/62332)), use the JSON\nform:\n\n```bash\nclaude mcp add-json humanpen -s user '{\"command\":\"npx\",\"args\":[\"-y\",\"humanpen-mcp\"],\"env\":{\"HUMANPEN_API_KEY\":\"hp_your_key\"}}'\n```\n</details>\n\n<details>\n<summary><b>OpenAI Codex</b></summary>\n\nIn `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.humanpen]\ncommand = \"npx\"\nargs = [\"-y\", \"humanpen-mcp\"]\nenv = { HUMANPEN_API_KEY = \"hp_your_key\" }\n```\n</details>\n\n<details>\n<summary><b>CodeBuddy / WorkBuddy</b></summary>\n\n```bash\ncodebuddy mcp add --scope user humanpen -- npx -y humanpen-mcp\n```\n\nIt also reads `${VAR}` in its config, so the key can stay in your environment\ninstead of the file:\n\n```json\n{ \"mcpServers\": { \"humanpen\": {\n  \"command\": \"npx\", \"args\": [\"-y\", \"humanpen-mcp\"],\n  \"env\": { \"HUMANPEN_API_KEY\": \"${HUMANPEN_API_KEY}\" }\n} } }\n```\n\n`~/.codebuddy/.mcp.json` for every project, `<project>/.mcp.json` for one.\n</details>\n\n<details>\n<summary><b>Gemini CLI</b></summary>\n\nIt has `gemini mcp add`, but the argument order differs between versions — run\n`gemini mcp add --help` and follow the usage line it prints. Pass the key with\n`-e HUMANPEN_API_KEY=...` and the scope with `-s user`; the default is\n`project`, which is only the directory you ran it in.\n</details>\n\n<details>\n<summary><b>Claude Desktop</b></summary>\n\nIn `claude_desktop_config.json`. **Use the absolute path to `npx`** — run\n`which npx` and paste the result: a desktop app is launched by the OS with a\nminimal `PATH`, so the bare name that works in your terminal often is not found\nhere, and the only symptom is that the tools never appear.\n\n```json\n{\n  \"mcpServers\": {\n    \"humanpen\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"humanpen-mcp\"],\n      \"env\": { \"HUMANPEN_API_KEY\": \"hp_your_key\" }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><b>Cursor / Windsurf / Cline</b></summary>\n\nAll three read the same shape — Cursor in `.cursor/mcp.json`, Windsurf in\n`~/.codeium/windsurf/mcp_config.json`, Cline in its MCP settings panel:\n\n```json\n{\n  \"mcpServers\": {\n    \"humanpen\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"humanpen-mcp\"],\n      \"env\": { \"HUMANPEN_API_KEY\": \"hp_your_key\" }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><b>OpenCode</b></summary>\n\nIn `opencode.json` — the key names differ slightly from everyone else's:\n\n```json\n{\n  \"mcp\": {\n    \"humanpen\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"humanpen-mcp\"],\n      \"environment\": { \"HUMANPEN_API_KEY\": \"hp_your_key\" }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><b>VS Code</b> — keeps the key out of the config file</summary>\n\n```json\n{\n  \"mcp\": {\n    \"inputs\": [\n      { \"type\": \"promptString\", \"id\": \"humanpenKey\", \"description\": \"HumanPen API key\", \"password\": true }\n    ],\n    \"servers\": {\n      \"humanpen\": {\n        \"command\": \"npx\",\n        \"args\": [\"-y\", \"humanpen-mcp\"],\n        \"env\": { \"HUMANPEN_API_KEY\": \"${input:humanpenKey}\" }\n      }\n    }\n  }\n}\n```\n\nVS Code prompts once and stores the key in its secret store, so it never lands\nin a file you might commit.\n</details>\n\n<details>\n<summary><b>From source</b>, or before the npm release lands</summary>\n\n```bash\ngit clone https://github.com/humanpen/humanpen-mcp\ncd humanpen-mcp && npm install && npm run build\n```\n\nThen point your client at `node /path/to/humanpen-mcp/dist/index.js` instead of\n`npx -y humanpen-mcp`.\n</details>\n\nAny MCP client works: this is a plain stdio server started by\n`npx -y humanpen-mcp` with `HUMANPEN_API_KEY` in its environment.\n\n## Tools\n\n| Tool | What it does | Credits |\n| --- | --- | --- |\n| `humanize_document` | Rewrite a `.docx`/`.pptx` to read as human-written and score lower on AI detectors. Optionally take a detection report to rewrite only its flagged passages. Length can be held to a whole-document word range, or to per-passage ranges (experimental — limiting words weakens AI-rate reduction). | yes |\n| `free_rehumanize` | Continue a finished `humanize_document` job for **free**: upload a fresh detection report for its result and only the still-flagged passages are rewritten. Once per job, with a daily cap; the report must match that result. | free |\n| `fix_citations` | Convert in-text citations and the reference list to APA 7, MLA 9, Harvard, Chicago, IEEE, Vancouver, GB/T 7714, AMA, ACS or OSCOLA. Body text untouched. | yes |\n| `condense_document` | Shorten a `.docx` to a target word count, keeping structure and citations. | yes |\n| `translate_document` | Translate `.docx`/`.pdf`/`.pptx`/`.xlsx`/`.epub`/`.html`/`.txt` between 12 languages, keeping layout. | yes |\n| `read_detection_report` | Read a Turnitin or iThenticate AI Writing report: overall AI percentage and the flagged passages. | free |\n| `check_job` | Look up a job and download its result. | free |\n| `get_credit_balance` | Credits remaining. | free |\n\n## Two things worth knowing\n\n**Jobs take minutes; tool calls do not.** Each operation waits about 55 seconds\n— enough for most documents — then returns a `job_id` with a note to call\n`check_job`. The work continues on the server either way; nothing is lost by the\ntool returning early.\n\n**`ai_percent` can be `null`, and that is usually good news.** Turnitin prints\n`*` instead of a number whenever AI writing comes in **under 20%** — it will not\nquantify that band, because too much of it is false positives. So `null` means\n\"under 20%, and Turnitin will say no more\", never \"0%\" and never \"no result\".\n\n## Questions people ask\n\n**Will this bring a Turnitin AI score down?**\nUsually under 20% in one pass with `balanced` — the threshold below which\nTurnitin prints `*` instead of a number. If it misses, hand the result back with\nthe new report; only the passages still flagged get rewritten.\n\n**Does it work with iThenticate too?**\nYes — pass either report. The format is read from the file.\n\n**Is my document sent to the model?**\nNo. It uploads the file and answers with a path. A 40-page paper costs no tokens.\n\n## Privacy Policy\n\nDocuments you pass to a tool are uploaded over HTTPS to HumanPen's API\n(`api.humanpen.net`) for processing; results are written back to your disk, and\nprocessed files are kept server-side for about 7 days so `check_job` and the\nfree re-humanize pass can find them. Document contents never enter the model's\ncontext. The full policy — what is collected, retention, and how to reach us —\nis at <https://humanpen.net/legal/privacy>.\n\n## Development\n\n```bash\nnpm install\nnpm run build\nHUMANPEN_API_KEY=hp_... node selftest.mjs sample.docx report.pdf\n```\n\n`selftest.mjs` spawns the built server and talks JSON-RPC to it over stdio the\nway a real client does — proving the protocol, the tool registrations, stdout\nhygiene and one end-to-end job, not merely that the functions return. It needs a\nlive key and spends credits, so it is a pre-release check rather than a CI step.\n\n## Links\n\n- [API documentation](https://api.humanpen.net/v1/docs.md) ·\n  [OpenAPI schema](https://api.humanpen.net/v1/openapi.json)\n- [humanpen-skill](https://github.com/humanpen/humanpen-skill) — the same\n  operations as an Agent Skill, if you would rather not run a server\n- [humanpen.net](https://humanpen.net)\n\nApache-2.0\n",
  "bytes": 10459,
  "sha": "210b8c91f7bfb3acc0ad55f83e96e2aecadba4e767fbad43039259e4a7e08a6d",
  "repo_slug": "humanpen/humanpen-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_humanpen_humanpen_mcp_9a8a1b92/readme"
}