Content
# humanizer-mcp
[](https://pypi.org/project/humanizer-mcp/)
[](https://www.npmjs.com/package/humanizer-mcp)
[](https://pypi.org/project/humanizer-mcp/)
[](LICENSE)
[](https://github.com/aousabdo/humanizer-mcp/actions/workflows/ci.yml)
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](https://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/`](skill/humanizer-mcp/) folder under *Settings → Capabilities → Skills*. See [skill/README.md](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/`](share/) — email either one, no further explanation needed:
>
> - [share/humanizer-mcp-friends-guide.pdf](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](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](#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)
```bash
# 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`:
```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`:
```bash
pip install humanizer-mcp && humanizer-mcp # pip
npx humanizer-mcp # npm launcher (delegates to uvx/pipx/python3)
```
### Try it with the MCP Inspector
```bash
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:
[](https://render.com/deploy?repo=https://github.com/aousabdo/humanizer-mcp)
**Fly.io** — always-on free tier:
```bash
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:
```bash
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:
```bash
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
```bash
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
```bash
git clone https://github.com/aousabdo/humanizer-mcp
cd humanizer-mcp
pip install -e ".[dev]"
pytest
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for more.
## License
MIT — see [LICENSE](LICENSE).
