Content
# WriteStat MCP Server
<p align="center">
<img src="https://raw.githubusercontent.com/labeveryday/writestat-mcp/main/assets/banner.png" alt="WriteStat MCP Architecture" width="800"/>
</p>
[](https://pypi.org/project/writestat-mcp/)
[](https://github.com/labeveryday/writestat-mcp/actions/workflows/tests.yml)
[](https://www.python.org/downloads/)
[](https://github.com/astral-sh/ruff)
[](https://opensource.org/licenses/MIT)
MCP server for text readability analysis and AI pattern detection. Helps writers identify AI-like patterns and improve readability.
Created by [Du'An Lightfoot](https://duanlightfoot.com) | [@labeveryday](https://github.com/labeveryday)
## Installation
```bash
pip install writestat-mcp
# Optional: ML-based detection (~500MB for torch/transformers)
pip install writestat-mcp[ml]
# Required: NLTK data
python -c "import nltk; nltk.download('punkt_tab')"
```
## Tools
| Tool | Description |
|------|-------------|
| `analyze_text` | Readability metrics (Flesch-Kincaid, SMOG, etc.) |
| `find_hard_sentences` | Complex sentences with explanations |
| `check_ai_phrases` | Pattern-based AI detection (60+ patterns) |
| `detect_ai_ml` | ML detection via GPT-2 perplexity (optional) |
| `batch_analyze` | Process multiple texts in parallel |
| `compare_texts` | Before/after comparison |
## Claude Desktop Setup
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"readability-mcp": {
"command": "uvx",
"args": ["writestat-mcp"]
}
}
```
## With Claude Code
```bash
# After PyPI publish
# Pattern detection only (lightweight)
claude mcp add writestat-mcp -- uvx writestat-mcp
# Or with ML detection (~500MB download)
claude mcp add writestat-mcp -- uvx "writestat-mcp[ml]"
# From local source
cd /path/to/writestat-mcp
pip install -e .
claude mcp add writestat-mcp -- writestat-mcp
```
## Example Prompts
**Full analysis workflow:**
> I just wrote this blog post. Check the readability, find any difficult sentences, and flag anything that sounds too AI-generated. Then suggest improvements:
**Editing pass:**
> This is my draft and my revised version. Compare them and tell me if the readability improved and if I removed the AI-sounding phrases. {First_draft} vs {second_draft}
**Quick AI check:**
> Does this paragraph have any AI tells? Be specific about which phrases to fix:
**Target audience check:**
> I'm writing for high school students. Is this text at the right reading level? Which sentences are too complex:
## AI Detection: What to Expect
This tool uses **heuristic pattern matching** and **zero-shot perplexity scoring**—not a fine-tuned classifier.
### How It Works
- **Pattern detection**: Catches stylistic markers (em dashes, filler phrases, buzzwords)
- **ML detection**: Measures perplexity, vocabulary diversity, burstiness
### Accuracy Context
Research shows fine-tuned RoBERTa models achieve ~99% F1 on ChatGPT detection ([Guo et al., 2023](https://arxiv.org/abs/2301.07597)). Our lightweight approach won't match that. It's designed for:
- Quick pattern screening
- Catching obvious AI tells
- Educational awareness about AI writing patterns
**Not suitable for**: Academic integrity decisions, high-stakes verification
### What the Research Found
The [HC3 paper](https://arxiv.org/abs/2301.07597) identified key ChatGPT markers we detect:
- Lower perplexity (more predictable) ✓
- Lower vocabulary diversity ✓
- Formal conjunctions ("Furthermore", "It's important to note") ✓
- Organized structure with clear transitions ✓
## Score Interpretation
### Readability (Flesch-Kincaid Grade)
| Grade | Audience |
|-------|----------|
| 5- | Elementary |
| 6-8 | Middle school |
| 9-12 | High school |
| 13+ | College |
### AI Probability (ML)
| Score | Interpretation |
|-------|----------------|
| 0-30 | Likely human |
| 30-60 | Uncertain |
| 60-100 | Likely AI |
## Requirements
- Python 3.10+
- Core: fastmcp, textstat, nltk
- Optional `[ml]`: torch, transformers
## License
MIT
## References
- [HC3: How Close is ChatGPT to Human Experts?](https://arxiv.org/abs/2301.07597) - Guo et al., 2023
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [FastMCP](https://github.com/jlowin/fastmcp)
Connection Info
You Might Also Like
markitdown
Python tool for converting files and office documents to Markdown.
Fetch
Retrieve and process content from web pages by converting HTML into markdown format.
oh-my-opencode
Background agents · Curated agents like oracle, librarians, frontend...
earl
Secure CLI proxy for AI agents — HCL-defined operation templates with OS...
add-mcp
The open MCP config tool - npx add-mcp
agentpool
A hub for managing diverse AI agents via YAML and standard protocols.