Skip to main content
Glama

humanpen-mcp

License MCP Node

English · 简体中文 · 日本語

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-mcp

Features

  • 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-mcp

It 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 build

Then 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

humanize_document

Rewrite a .docx/.pptx to read as human-written and score lower on AI detectors. Optionally take a detection report, or passages you choose, to rewrite only those. Length can be held to a whole-document word range, or to per-passage ranges (experimental — limiting words weakens AI-rate reduction).

yes

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

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

condense_document

Shorten a .docx to a target word count, or only chosen passages, each to its own budget, keeping structure and citations. Condense by rewriting sentences, or by deleting whole low-value sentences and keeping the rest verbatim.

yes

translate_document

Translate .docx/.pdf/.pptx/.xlsx/.epub/.html/.txt between 12 languages, keeping layout.

yes

read_detection_report

Read a Turnitin or iThenticate AI Writing report: overall AI percentage and the flagged passages.

free

check_job

Look up a job and download its result.

free

list_jobs

List your document jobs, newest first, with their status and credits.

free

cancel_job

Cancel a queued or running job; its reserved credits are returned.

free

retry_job

Run a failed or cancelled job again with the same settings.

yes

get_credit_balance

Credits remaining.

free

start_project

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

get_project

Where a project stands: what it needs from you, the scoping questions or the plan, the agents' last message, the deliveries.

free

wait_for_project

Wait until a project needs you or has finished.

free

act_on_project

Confirm the plan, answer questions, top up, take the work as it is, pause, resume, cancel, give feedback.

confirming, topping up

message_project

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; deliver_now hands it over at once.

yes

download_delivery

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.pdf

selftest.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.

Apache-2.0

Available Tools

17 tools
act_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 jobA
Destructive

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 balanceA
Read-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 projectA
Read-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 jobsA
Read-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 reportA
Read-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 projectA
Read-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

    A4/5.0

    Scored across 17 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers