Humanizer

PyPI version npm version Python versions License: MIT CI

An MCP (Model Context Protocol) server that measures AI-detection risk in a piece of text and tells you — line by line — what to change. Works with Claude Code, Claude Desktop, and any MCP-compatible client.

Just want to use it? Go to humanizer.analyticadss.com — copy the URL, paste it into Claude's Connectors, done. The rest of this README is for developers and people self-hosting.

Rather than running your prose through a black-box "humanizer," this server analyzes it against known detection signals (vocabulary, burstiness, contraction usage, paragraph uniformity, em dashes, first-person voice) and returns a structured report with a 0–100 risk score and a concrete rewrite plan. The actual rewriting is left to the LLM that's driving the conversation — which is the point: a planner, not a laundering service.

Tools

Tool	What it does
humanizer_humanize_text	Returns the rewritten text. Applies vocabulary swaps, phrase removal, contractions, em-dash cleanup, plus before/after scores. The LLM caller polishes for context.
humanizer_analyze_ai_tells	Full analysis with risk score, fix recommendations, and a mechanical rewrite as a starting point.
humanizer_quick_vocab_scan	Fast word- and phrase-level scan with replacement suggestions.
humanizer_get_rewrite_instructions	Step-by-step rewrite plan, tailored to text type (blog / business / academic / email / general).
humanizer_compare_before_after	Side-by-side metrics for an original and a rewrite, with a PASS / IMPROVED / NEEDS MORE WORK verdict.
humanizer_get_banned_words	The full vocabulary and phrase ban list, for reference.

Three ways to use it

Path	Best for	What you do
Hosted URL (no install, deterministic)	claude.ai, Claude Desktop, Claude for Chrome — including Free plan	Paste one URL into Settings → Connectors → Add custom connector.
Skill (no install, no infra, estimated)	Same surfaces, plus people who don't want to use up their 1 free-tier connector slot	Upload the skill/humanizer-mcp/ folder under Settings → Capabilities → Skills. See skill/README.md.
Local install (uvx / npx)	Claude Code on the terminal, Desktop with stdio	One command in a shell.

Sharing with non-technical users? Two PDFs in share/ — email either one, no further explanation needed:

• share/humanizer-mcp-friends-guide.pdf — 2 pages. Truly non-technical: download a zip, upload it to Claude, done. No install.
• share/humanizer-mcp-boss-guide.pdf — 3 pages. Semi-technical Windows users who can install an app and edit a config file. Sets up the full MCP server with Claude Desktop.

Path A — add as a Custom Connector (zero install)

Works in claude.ai (web), Claude Desktop, and Claude for Chrome — all four surfaces share the connector list once you're signed in. Available on every plan including Free (Free is limited to one custom connector).

A hosted reference instance is up — feel free to use it for casual evaluation:

https://humanizer-api.analyticadss.com/mcp

For production / privacy-sensitive use, deploy your own with the included Dockerfile (see Hosting below — Fly.io takes ~3 minutes). The hosted instance is on a free Fly tier with no SLA, no support, and no privacy guarantees — your text passes through it.

To add it to your Claude:

1. Open Claude → Settings → Connectors.
2. Click Add custom connector.
3. Paste the URL above (or your own hosted instance's /mcp URL).
4. Save. The five humanizer_* tools become available in any chat.

That's the whole install for non-technical users — they never touch a terminal.

Path B — install locally (Claude Code / Desktop with stdio)

# Claude Code, one line
claude mcp add humanizer -- uvx humanizer-mcp

For Claude Desktop with a local stdio server, add this to claude_desktop_config.json:

{
  "mcpServers": {
    "humanizer": {
      "command": "uvx",
      "args": ["humanizer-mcp"]
    }
  }
}

Config location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Other ways to launch the local binary if you don't want uvx:

pip install humanizer-mcp && humanizer-mcp     # pip
npx humanizer-mcp                              # npm launcher (delegates to uvx/pipx/python3)

Try it with the MCP Inspector

npx @modelcontextprotocol/inspector uvx humanizer-mcp

Hosting

To create the URL in Path A, deploy the included Dockerfile. The repo ships with a Render Blueprint and a Fly config:

Render — easiest, free tier, auto-deploys from the GitHub repo:

Deploy to Render

Fly.io — always-on free tier:

fly launch --copy-config --name humanizer-mcp
fly deploy

Anywhere else — the Dockerfile reads PORT from the environment and binds to 0.0.0.0, so it runs on Railway, Heroku, Cloud Run, ECS, or your own box:

docker build -t humanizer-mcp .
docker run -p 8000:8000 humanizer-mcp

Cloudflare Tunnel from your laptop — zero hosting cost, only up while your machine is on:

brew install cloudflared
pipx install humanizer-mcp        # or: pip install humanizer-mcp
humanizer-mcp --http --port 8000 &
cloudflared tunnel --url http://localhost:8000
# copy the trycloudflare.com URL it prints

The MCP endpoint is at /mcp (streamable HTTP). The server is stateless and unauthenticated — anyone with the URL can call the tools, but there are no secrets and no destructive operations to abuse.

Run the HTTP server locally

humanizer-mcp --http --port 8000
# point a client at http://127.0.0.1:8000/mcp

Verify it works

Once installed by any path, in any Claude chat ask:

"What humanizer tools do you have available?"

Claude should list five: humanizer_analyze_ai_tells, humanizer_quick_vocab_scan, humanizer_get_rewrite_instructions, humanizer_compare_before_after, humanizer_get_banned_words.

Then try the canonical test:

"Score this for AI tells: 'In today's rapidly evolving digital landscape, it's important to note that businesses must leverage cutting-edge solutions to navigate the multifaceted challenges they face.'"

You should get a score in the HIGH bucket (≥ 60), the signals that fired, and a line-by-line fix list.

Troubleshooting

Symptom	Likely cause	Fix
claude mcp list shows server but no tools	uvx isn't on $PATH for the Claude Code subprocess	which uvx; add ~/.local/bin to $PATH in your shell rc
humanizer-mcp: command not found after pip install	pip user-install bin not on $PATH	Use python3 -m humanizer_mcp instead — always works
Claude Desktop has no hammer icon	Config JSON syntax error	python3 -m json.tool < claude_desktop_config.json to validate
npx humanizer-mcp hangs ~30s on first run	Launcher is shelling to uvx, which downloads deps on first use	Wait it out; subsequent runs are instant
Render-hosted: 406 spam in logs	Health Check Path is /mcp; should be /health	Settings → Health & Alerts → set to /health
Render-hosted: pip install killed during build	OOM on free tier (512MB) — pydantic-core native compile spikes	Switch to Fly free tier or upgrade Render to Starter
Custom Connector add fails on claude.ai Free	Already at the 1-connector limit	Remove an unused connector; or upgrade plan

Example prompts

With the server connected to Claude, you can say things like:

• "Analyze this blog post for AI tells and tell me what to change."
• "Run a quick vocab scan on this paragraph."
• "Give me rewrite instructions for this academic abstract — keep it formal but fix the burstiness."
• "Compare these two drafts. Did my edit actually lower the detection risk?"

Claude picks the right tool automatically.

How the risk score works

The 0–100 score combines eight signals:

1. AI vocabulary hits — words statistically overrepresented in LLM output (delve, crucial, leverage, myriad, …).
2. AI phrase hits — cliché structural tells (it's important to note, in the ever-evolving, at the end of the day, …).
3. Burstiness — coefficient of variation of sentence lengths. AI writing clusters around a single length; humans mix short fragments and long digressions.
4. Contractions — expanded forms (it is, do not) read as AI-formal; contractions read as conversational.
5. Paragraph uniformity — AI tends to produce paragraphs of similar size.
6. Rhetorical questions — near-absent in AI prose above 200 words.
7. First-person voice — AI avoids I, we, my, our unless prompted.
8. Em dashes — a ChatGPT signature; heavy use is a strong signal.

Each signal adds to the score independently; the total is clamped to 100 and bucketed into LOW (≤ 20), MEDIUM (21–50), or HIGH (51+).

Development

git clone https://github.com/aousabdo/humanizer-mcp
cd humanizer-mcp
pip install -e ".[dev]"
pytest

See CONTRIBUTING.md for more.

License

MIT — see LICENSE.