wordsmith-mcp
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., "@wordsmith-mcp Summarize this article in 3 sentences and list its top keywords."
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.
Wordsmith MCP
An MCP (Model Context Protocol) server that gives any MCP-compatible AI client a set of offline text analysis and rewriting tools — statistics, extractive summaries, keyword extraction, readability scoring, naming-case conversion, entity extraction and text diffing.
No API keys. No network calls. No state stored anywhere. Everything runs locally on the text you pass in, which makes it fast, free, and safe to point at private documents.
Built with the MCP Python SDK.
Why this exists
Language models are great at judging text but surprisingly unreliable at measuring it — ask one for an exact word count or a Flesch score and it will guess. Wordsmith hands the model a deterministic calculator for those jobs, so answers about a document's length, difficulty and key terms are computed rather than estimated.
Related MCP server: mhlabs-mcp-tools
Tools
Tool | What it does | Key parameters |
| Characters, words, unique words, sentences, paragraphs, lines, average word/sentence length, estimated reading time |
|
| Extractive summary — scores sentences by meaningful-word frequency and returns the best ones in original order |
|
| Most frequent meaningful words with counts and relative frequency; stopwords filtered |
|
| Flesch Reading Ease + Flesch–Kincaid grade level, with a plain-language interpretation |
|
| Converts to |
|
| Pulls out emails, URLs, hashtags, mentions, phone numbers and standalone numbers |
|
| Unified line-by-line diff between a draft and a revision |
|
All tools are annotated readOnlyHint: true, openWorldHint: false — they never mutate
anything and never reach out to the internet.
Quick start (local, stdio)
git clone https://github.com/mirza1272/wordsmith-mcp.git
cd wordsmith-mcp
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .Run it:
wordsmith-mcpThe server speaks MCP over stdio and will sit there waiting for a client — that is correct behaviour, not a hang. Clients start it themselves; see below.
Verify it works
python scripts/smoke_test.pyThis spins up the server as a real MCP client would, lists the tools and calls every one of them, printing the results.
Run the unit tests
pip install -e ".[dev]"
pytest -qConnecting it to a client
Claude Desktop
Edit claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"wordsmith": {
"command": "/absolute/path/to/wordsmith-mcp/.venv/bin/wordsmith-mcp"
}
}
}Restart Claude Desktop, then ask something like "How readable is this paragraph, and what are its top 5 keywords?"
Claude Code
claude mcp add wordsmith -- /absolute/path/to/wordsmith-mcp/.venv/bin/wordsmith-mcpCursor / Windsurf / other clients
Any client that accepts an mcpServers block uses the same shape as the Claude Desktop
example above.
MCP Inspector (visual debugging)
npx @modelcontextprotocol/inspector .venv/bin/wordsmith-mcpOpens a browser UI where each tool can be called by hand and the raw JSON-RPC traffic inspected.
HTTP mode (for hosted deployments)
The same server also speaks streamable HTTP, which is what hosted marketplaces use:
TRANSPORT=http PORT=8081 wordsmith-mcpThe MCP endpoint is then at http://localhost:8081/mcp.
Env var | Default | Meaning |
|
|
|
|
| Bind address in HTTP mode |
|
| Bind port in HTTP mode |
|
| HTTP path the MCP endpoint is served on |
Deploying
Smithery's publish form takes a live HTTPS MCP endpoint, so the server is hosted first and then
listed. Dockerfile and render.yaml are included for that; smithery.yaml is kept for hosts
that build the container directly.
Full walkthrough: DEPLOY.md.
In short: deploy the container to a host (Render, Railway, Fly.io — render.yaml is included),
then publish the resulting https://<host>/mcp URL on Smithery.
Building the container locally first is a good sanity check:
docker build -t wordsmith-mcp .
docker run --rm -p 8081:8081 wordsmith-mcpProject structure
wordsmith-mcp/
├── src/wordsmith_mcp/
│ ├── __init__.py # package exports
│ ├── __main__.py # python -m wordsmith_mcp
│ ├── server.py # MCP server: tool definitions and schemas
│ └── textutils.py # pure text logic, no MCP imports
├── scripts/smoke_test.py # end-to-end client that exercises every tool
├── tests/test_textutils.py
├── examples/claude_desktop_config.json
├── Dockerfile
├── smithery.yaml
├── pyproject.toml
└── README.mdtextutils.py holds the algorithms and imports nothing from MCP, so the logic is unit-testable
on its own; server.py is a thin protocol layer that describes those functions to the model.
How it works (a 60-second tour of MCP)
MCP is a JSON-RPC protocol that lets an AI client discover and call tools exposed by a server.
The client launches the server (as a subprocess over stdio, or connects over HTTP).
Client and server exchange an
initializehandshake announcing protocol version and capabilities.The client calls
tools/list. The SDK generates each tool's JSON Schema from the Python type hints andField(...)descriptions, so the model sees exactly what arguments are valid.When the model decides a tool is needed, the client sends
tools/callwith arguments; the server runs the Python function and returns the result — both as human-readable text and asstructuredContentmatching the declared output schema.
Adding a tool is therefore just writing a typed Python function and decorating it with
@mcp.tool(...).
Further reading in this repo
WRITEUP.md— my write-up on using an existing MCP server (Context7) and what I learned building this one.DEPLOY.md— step-by-step guide to publishing this server on Smithery and Glama.
License
MIT — see LICENSE.
Available Tools
7 toolsconvert_caseConvert text caseARead-onlyIdempotent
Rewrite text into a naming convention: snake_case, kebab-case, slug, camelCase, PascalCase, CONSTANT_CASE, Title Case, Sentence case, UPPER or lower. Handles input that is already in any of these styles.
Inputs: text (required), style (required). Returns: result
diff_textsDiff two textsARead-onlyIdempotent
Return a unified diff between two versions of a text, line by line, so edits between a draft and a revision can be reviewed precisely. Returns a note when the two inputs are identical.
Inputs: after (required), before (required), context_lines. Returns: result
extract_entitiesExtract entitiesARead-onlyIdempotent
Pull structured items out of free text: email addresses, URLs, #hashtags, @mentions, phone numbers and standalone numbers. Results are de-duplicated and returned in the order they first appear.
Inputs: text (required). Returns: Structured items pulled out of free text.
extract_keywordsExtract keywordsARead-onlyIdempotent
Return the most frequent meaningful words in the text, with counts and relative frequency. Common English stopwords and very short tokens are filtered out. Useful for tagging, SEO checks or spotting what a document is actually about.
Inputs: text (required), limit, min_length. Returns: result
readabilityScore readabilityARead-onlyIdempotent
Compute Flesch Reading Ease and Flesch-Kincaid grade level for the text, with a plain-language interpretation. Use it to check whether a draft matches its intended audience before publishing.
Inputs: text (required). Returns: Flesch-family readability scores.
summarize_textSummarize textARead-onlyIdempotent
Produce an extractive summary by scoring each sentence on the frequency of the meaningful words it contains and returning the highest-scoring sentences in their original order. Works fully offline; no model call is made.
Inputs: text (required), max_sentences. Returns: result
text_statsAnalyze text statisticsARead-onlyIdempotent
Count characters, words, unique words, sentences, paragraphs and lines in a piece of text, plus average word/sentence length and an estimated reading time. Use this to check length limits or to profile a draft before editing.
Inputs: text (required). Returns: Structural counts for a piece of text.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose: statistics, summarization, keywords, readability, case conversion, entity extraction, and diffing. While several tools analyze text, their outputs are different enough that an agent should not confuse them.
Most tools follow a verb_noun pattern such as summarize_text, extract_keywords, convert_case, and diff_texts. text_stats and readability are minor deviations that are still readable and predictable.
Seven tools is a well-scoped size for a text analysis and transformation server. Each tool covers a distinct utility without unnecessary overlap or bloat.
The toolkit covers the core text-analysis workflow: profiling, summarizing, keyword extraction, readability, transformations, entity extraction, and diffing. Minor gaps like sentiment analysis or language detection are common additions but not clearly required for the stated purpose.
Maintenance
Related MCP Connectors
Text generation over MCP: prose, emails, blog outlines, SQL, humanizing, text diffs, fake data.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
Free OpenAI-compatible inference with signed provenance receipts and 3 focused MCP tools.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceIntegrates local language models (like Qwen3-8B) with MCP clients, providing tools for chat, code analysis, text generation, translation, and content summarization using your own hardware.-
- AlicenseNot gradedqualityDmaintenanceModular MCP server providing text preprocessing and NLP tools for AI agent ecosystems.MIT
- AlicenseBqualityBmaintenanceEnables local, offline AI-text detection over MCP with read-only tools for status checking and statistical analysis of text using calibrated compact models.2BSD 3-Clause
- AlicenseAqualityFmaintenanceLets MCP clients delegate private or bulk text tasks to a local OpenAI-compatible LLM while keeping data on the machine.11MIT