humanpen-mcp
OfficialHumanPen MCP provides document-processing and cloud-research tools for common office/document formats, with job and credit management.
Humanize documents: rewrite
.docx/.pptxto reduce AI-detector scores, either whole-document, selected passages, or only flagged passages from a Turnitin/iThenticate report.Free re-humanize: continue a finished humanize job for free using a fresh matching detection report, rewriting only still-flagged passages within server limits.
Fix citations: convert in-text citations and reference lists to one of 12 citation styles without changing body text.
Condense documents: shorten a
.docxto a target word count or shorten selected passages, by rewriting or deleting low-value sentences.Translate documents: translate
.docx/.pdf/.pptx/.xlsx/.epub/.html/.txtamong 12 languages while preserving layout.Read detection reports: extract overall AI percentage and flagged passages from Turnitin/iThenticate report PDFs.
Manage jobs: check status and download results, list jobs, cancel queued/running jobs, retry failed/cancelled jobs, and check credit balance.
Run research projects: start cloud-agent research/data/writing projects with local files, inspect status, wait, answer scoping questions, confirm plans, message agents, act on projects, and download delivered zip files.
Preserve document structure: formatting, tables, images, citations, footnotes, equations, and layout are generally retained; paid tools cost credits and should be confirmed with the user first.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@humanpen-mcp Humanize my document to reduce AI detection score."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
humanpen-mcp
Website · Pricing · Developer docs
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
Humanize what's flagged. Preserve the rest. An MCP server for HumanPen — 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.
claude mcp add humanpen -s user -e HUMANPEN_API_KEY=hp_your_key -- npx -y humanpen-mcpFeatures
Selective rewriting by detection report — import a Turnitin / iThenticate AI Writing Report to pinpoint flagged passages; unflagged content is never touched
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
Academic structure preserved — in-text citations, reference lists, footnotes, TOC fields, cross-references, figure numbering, equations, and special formatting are treated as protected objects
No error injection — restructures meaning and syntax to change expression; never adds grammar mistakes, spelling errors, or awkward sentences as a detection strategy
Full-length documents — no per-input word limit; a single file can be up to 100 MB, no splitting into text boxes
Free to keep going — still flagged? Re-humanize for free with a fresh report until the AI rate falls to
*or 0%Word-count control (experimental) — set a min/max word range to keep the output within a target length
Pay per rewrite — billed on words actually changed, not the whole document; failed and cancelled jobs cost nothing; credits never expire
Related MCP server: docx-forge-mcp
Get a key
Sign up at https://humanpen.net and create a key at https://humanpen.net/settings/api-keys. New accounts start with free credits, enough to put a document through and see what comes back.
The key goes in an environment variable, never in a URL. URLs end up in server logs, proxy logs, shell history and screenshots.
Install
claude mcp add humanpen -s user -e HUMANPEN_API_KEY=hp_your_key -- npx -y humanpen-mcp-s user puts it in every project. The default scope is local, which
loads the server only in the directory you ran the command from — and looks
like a broken install the first time you open Claude Code somewhere else.
If your version rejects -e (reported
upstream), use the JSON
form:
claude mcp add-json humanpen -s user '{"command":"npx","args":["-y","humanpen-mcp"],"env":{"HUMANPEN_API_KEY":"hp_your_key"}}'In ~/.codex/config.toml:
[mcp_servers.humanpen]
command = "npx"
args = ["-y", "humanpen-mcp"]
env = { HUMANPEN_API_KEY = "hp_your_key" }codebuddy mcp add --scope user humanpen -- npx -y humanpen-mcpIt also reads ${VAR} in its config, so the key can stay in your environment
instead of the file:
{ "mcpServers": { "humanpen": {
"command": "npx", "args": ["-y", "humanpen-mcp"],
"env": { "HUMANPEN_API_KEY": "${HUMANPEN_API_KEY}" }
} } }~/.codebuddy/.mcp.json for every project, <project>/.mcp.json for one.
It has gemini mcp add, but the argument order differs between versions — run
gemini mcp add --help and follow the usage line it prints. Pass the key with
-e HUMANPEN_API_KEY=... and the scope with -s user; the default is
project, which is only the directory you ran it in.
In claude_desktop_config.json. Use the absolute path to npx — run
which npx and paste the result: a desktop app is launched by the OS with a
minimal PATH, so the bare name that works in your terminal often is not found
here, and the only symptom is that the tools never appear.
{
"mcpServers": {
"humanpen": {
"command": "npx",
"args": ["-y", "humanpen-mcp"],
"env": { "HUMANPEN_API_KEY": "hp_your_key" }
}
}
}All three read the same shape — Cursor in .cursor/mcp.json, Windsurf in
~/.codeium/windsurf/mcp_config.json, Cline in its MCP settings panel:
{
"mcpServers": {
"humanpen": {
"command": "npx",
"args": ["-y", "humanpen-mcp"],
"env": { "HUMANPEN_API_KEY": "hp_your_key" }
}
}
}In opencode.json — the key names differ slightly from everyone else's:
{
"mcp": {
"humanpen": {
"type": "local",
"command": ["npx", "-y", "humanpen-mcp"],
"environment": { "HUMANPEN_API_KEY": "hp_your_key" }
}
}
}{
"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 prompts once and stores the key in its secret store, so it never lands in a file you might commit.
git clone https://github.com/humanpen/humanpen-mcp
cd humanpen-mcp && npm install && npm run buildThen point your client at node /path/to/humanpen-mcp/dist/index.js instead of
npx -y humanpen-mcp.
Any MCP client works: this is a plain stdio server started by
npx -y humanpen-mcp with HUMANPEN_API_KEY in its environment.
Tools
Tool | What it does | Credits |
| Rewrite a | yes |
| Continue a finished | free |
| 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 |
| Shorten a | yes |
| Translate | yes |
| Read a Turnitin or iThenticate AI Writing report: overall AI percentage and the flagged passages. | free |
| Look up a job and download its result. | free |
| List your document jobs, newest first, with their status and credits. | free |
| Cancel a queued or running job; its reserved credits are returned. | free |
| Run a failed or cancelled job again with the same settings. | yes |
| Credits remaining. | free |
| Hand a research, data analysis or writing task to HumanPen's cloud agents, with local files as its input: they scope it with you, propose a plan, do the work, have it reviewed and deliver files. Needs a key created with Research projects ticked. | once a plan is confirmed |
| Where a project stands: what it needs from you, the scoping questions or the plan, the agents' last message, the deliveries. | free |
| Wait until a project needs you or has finished. | free |
| Confirm the plan, answer questions, top up, take the work as it is, pause, resume, cancel, give feedback. | confirming, topping up |
| Write to the agents, with files: more context, or changes after a delivery (a new round). While they work they read it after the step they are on; | yes |
| Save a delivered version as a zip. | free |
Three things worth knowing
Jobs take minutes; tool calls do not. Each operation waits about 55 seconds
— enough for most documents — then returns a job_id with a note to call
check_job. The work continues on the server either way; nothing is lost by the
tool returning early.
ai_percent can be null, and that is usually good news. Turnitin prints
* instead of a number whenever AI writing comes in under 20% — it will not
quantify that band, because too much of it is false positives. So null means
"under 20%, and Turnitin will say no more", never "0%" and never "no result".
A research project asks before it spends. Its plan comes back to you to confirm with
act_on_project (it is then charged by what it uses; there is no price up front), unless you start it with autonomy and a max_credits you are willing to spend: then it confirms
plans that fit, answers with the recommended answers and goes on by itself, never past that cap for the whole
project. A project runs for minutes to hours; wait_for_project waits about 55 seconds at a time, so call it again
until the project needs you or is done.
Questions people ask
Will this bring a Turnitin AI score down?
Usually under 20% in one pass with balanced — the threshold below which
Turnitin prints * instead of a number. If it misses, hand the result back with
the new report; only the passages still flagged get rewritten.
Does it work with iThenticate too? Yes — pass either report. The format is read from the file.
Is my document sent to the model? No. It uploads the file and answers with a path. A 40-page paper costs no tokens.
Privacy Policy
Documents you pass to a tool are uploaded over HTTPS to HumanPen's API
(api.humanpen.net) for processing; results are written back to your disk, and
processed files are kept server-side for about 7 days so check_job, retry_job
and the free re-humanize pass can find them. Document contents never enter the model's
context. The full policy — what is collected, retention, and how to reach us —
is at https://humanpen.net/legal/privacy.
Development
npm install
npm run build
HUMANPEN_API_KEY=hp_... node selftest.mjs sample.docx report.pdfselftest.mjs spawns the built server and talks JSON-RPC to it over stdio the
way a real client does — proving the protocol, the tool registrations, stdout
hygiene and one end-to-end job, not merely that the functions return. It needs a
live key and spends credits, so it is a pre-release check rather than a CI step.
Links
humanpen-skill — the same operations as an Agent Skill, if you would rather not run a server
Apache-2.0
Available Tools
17 toolsact_on_projectAct on a research projectA
Take one of the project's allowed_actions, with the ids it names: confirm_plan (spec_version; starts the paid work - only once the user agreed to the plan; it is charged by what it uses), answer (answers: question id -> answer), top_up (pause_id; max_credits raises a credit cap that ran out), one_more_round, accept_as_is, pause, resume, cancel, feedback (version, value), deliver_now (the agents read the waiting messages at once, interrupting the step they are on). COSTS CREDITS for confirm_plan, top_up, one_more_round and the scoping answers.
Inputs: action (required), project_id (required), text, value, +5 more.
cancel_jobCancel a jobADestructive
Cancel a document job that is still queued or running. Its reserved credits are returned - a cancelled job is never charged - and retry_job can run it again later. Free.
Inputs: job_id (required).
check_jobCheck a jobA
Look up a job by id, and download its result if it has finished. Use this after a tool returned before the job was done.
Inputs: job_id (required), output_path, document_path.
condense_documentCondense a documentA
Shorten a .docx, keeping meaning, structure and citations: the whole document to max_words, or only chosen passages (segments), each to its own budget. Saves the result next to the source and returns its path. COSTS CREDITS at 20 per 1,000 words processed (10 minimum) - say so and get agreement first.
Inputs: document_path (required), mode, segments, max_words, +3 more.
download_deliveryDownload a research project deliveryA
Save a delivered version of a research project (the latest unless version is given) as a zip in a directory, and return its path. Free.
Inputs: directory (required), project_id (required), version.
fix_citationsConvert citation formatA
Rewrite a .docx's in-text citations and reference list into one target style, leaving the body text alone. Saves the result next to the source and returns its path. COSTS CREDITS at 5 per 1,000 words processed (10 minimum) - say so and get agreement first.
Inputs: style (required), document_path (required), output_path, instructions, +1 more.
free_rehumanizeRe-humanize a job's still-flagged passages for freeA
Continue a finished humanize job for FREE. Upload a fresh detection report for that job's result; only the passages it still flags are rewritten, at no credit cost. The server enforces strict limits: one free continuation per job, a per-day cap, the report must be of THAT job's own result (>=90% match) and show >=20% AI, and the result must still exist (kept ~7 days). If a limit is not met it returns a clear reason - relay it and stop; do not retry or silently fall back to a paid job. Pass the job_id a prior humanize_document (or check_job) returned.
Inputs: job_id (required), report_path (required), segments, strategy, +3 more.
get_credit_balanceCheck the credit balanceARead-only
How many credits the account has. Per 1,000 words processed: humanize 100 credits, citation fixes 5, condensing 20, translation 10, with a 10-credit minimum per job. Worth checking before a large document.
Inputs: no named parameters.
get_projectLook at a research projectARead-only
Where a research project stands: its state (queued, working, input_required, completed, failed, cancelled, rejected), what it needs from the user, the scoping questions or the plan, the agents' last message, deliveries, credits used, and the actions allowed now. Free.
Inputs: project_id (required).
humanize_documentHumanize a documentA
Rewrite a .docx or .pptx so it reads as human-written and scores lower on AI detectors, keeping meaning, citations, tables and layout. Optionally pass a Turnitin/iThenticate AI report, or passages of your own (segments), to rewrite only those. If a fresh report still flags the result, run this tool again on the rewritten file with that new report - only the still-flagged passages are touched, and balanced remains the right strategy for the second pass. Saves the result next to the source and returns its path. COSTS CREDITS at 100 per 1,000 words processed (10 minimum) - say so and get agreement first.
Inputs: document_path (required), segments, strategy, max_words, +5 more.
list_jobsList jobsARead-only
List this account's document jobs, newest first, with their status and credits - to find a job id for check_job, cancel_job or retry_job. Free.
Inputs: type, limit, offset.
message_projectMessage a research projectA
Write to a project's agents, with local files if any: answer in the user's own words, add context, or after a delivery ask for changes (a new round). While they work, they read it after the step they are on (usually seconds); deliver_now hands it over at once, interrupting that step. COSTS CREDITS: the turns it starts are charged by use.
Inputs: text (required), project_id (required), files, deliver_now.
read_detection_reportRead an AI-detection reportARead-only
Read a Turnitin or iThenticate AI Writing report PDF: returns the overall AI percentage and the flagged passages. Free - reads the file without starting a job. Pass the same report to humanize_document to rewrite only what was flagged.
Inputs: report_path (required), type, include_segments.
retry_jobRetry a jobA
Run a failed or cancelled document job again with the same settings, from its stored source (kept about 7 days). Pass document_path to wait and save the result there, as the other tools do. COSTS CREDITS like the original job - say so and get agreement first.
Inputs: job_id (required), output_path, wait_seconds, document_path.
start_projectStart a research projectA
Hand a research, data analysis or writing task to HumanPen's cloud agents, with local files as its input: they scope it with the user, propose a plan, do the work, have it reviewed and deliver files. COSTS CREDITS once a plan is confirmed (charged by use; there is no price up front): show the user the plan and get their agreement before act_on_project confirm_plan, unless they set autonomy with a max_credits. Needs an API key with "Research projects" ticked.
Inputs: request (required), lang, files, title, +1 more.
translate_documentTranslate a documentA
Translate a document into another language while keeping its layout, tables, images and formulas. Takes .docx, .pdf, .pptx, .xlsx, .epub, .html and .txt. Saves the result next to the source and returns its path. COSTS CREDITS at 10 per 1,000 words processed (10 minimum) - say so and get agreement first.
Inputs: target_lang (required), document_path (required), output_path, source_lang, +1 more.
wait_for_projectWait for a research projectARead-only
Wait until a research project needs the user or has finished (its state is no longer queued or working), up to wait_seconds, then say where it stands as get_project does. Free. If it is still working, call it again with the after_seq it returns.
Inputs: project_id (required), after_seq, wait_seconds.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools target a distinct resource+action: the document tools (humanize/condense/fix_citations/translate) are cleanly separated, as are the project tools (start/get/wait/act/message/download). The main friction is the parallel 'job' vs 'project' vocabularies: check_job, retry_job, list_jobs and free_rehumanize sit close to the project lifecycle tools, and free_rehumanize vs retry_job (both re-run work on an existing job) could be confused at a glance, though the descriptions do disambiguate them.
Nearly all names are snake_case verb_noun (humanize_document, condense_document, translate_document, list_jobs, cancel_job, retry_job, get_project, download_delivery). Deviations are minor: free_rehumanize leads with an adjective, act_on_project/wait_for_project insert a preposition, and the noun flips between 'job' and 'project' for related concepts.
17 tools is on the heavy side of the sweet spot, but the server genuinely covers two workflows (document rewriting and cloud research projects) plus job lifecycle and credits, so each tool maps to a real operation. Nothing looks like padding, though a few project tools could arguably be folded into a single action-dispatcher.
Document handling covers rewrite/condense/citations/translate plus report reading, credit check, and a full job lifecycle (list, check, cancel, retry, free continuation). The project side covers scoping through delivery and actions, but there is no list_projects equivalent to list_jobs, so an agent cannot discover project ids outside its own session and there is no delete/purge for finished work.
Maintenance
Related MCP Connectors
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
Walter Remote MCP Server — AI humanization and detection tools
Convert, create and edit Word, PowerPoint, Excel and PDF documents from any AI agent.
An agent-first office suite Claude & ChatGPT read and write over one MCP URL.
Related MCP Servers
- AlicenseAqualityNot gradedmaintenanceAn MCP server that enables AI agents to instantly convert Markdown into beautiful, ready-to-deliver Word, PDF, HTML with sidebars, and Slideshow documents, bridging the "last mile" of AI content generation.728 npm1-
- AlicenseAqualityDmaintenanceMCP server for Word document (.docx) creation and manipulation — the production-grade document automation tool for AI agents.955 npmMIT
- FlicenseNot gradedqualityDmaintenanceMCP server that provides document conversion and processing tools, enabling AI assistants to handle document formats through natural language.-
- FlicenseNot gradedqualityDmaintenanceMCP server for document conversion and processing, enabling AI assistants to handle various document formats.-