Writing a README that actually gets installed
First three lines decide. Show the install command, the 'what it does' in one sentence, and a copy-paste config snippet. The README anatomy that turns viewers into users.
Writing a README that actually gets installed
Most MCP server READMEs are technically correct and conversion-poor. They explain the architecture before showing the install command. They list features before showing what the thing does. They assume you've already decided to install it. Reality: 95% of your visitors decide in 30 seconds whether they're installing or closing the tab. This recipe is the README anatomy that wins those 30 seconds.
Schritt 1: The first 30 seconds, the only screen most visitors see
What's above the fold (no scrolling, default GitHub viewport) decides everything. Your slot has space for ~6 lines:
# your-mcp-server
[](https://github.com/you/your-mcp-server/actions/workflows/ci.yml) [](https://www.npmjs.com/package/your-mcp-server) [](LICENSE)
> **One-sentence description that names the use case.** Not "MCP server for X", say what the user gets, in their language.
## Install
\`\`\`bash
claude mcp add your-server -s user -- npx -y your-mcp-server
\`\`\`
Six lines. After scanning these, the visitor knows:
- What it does (the blockquote)
- That it's maintained (badges)
- How to install it (copy-paste command)
If they want more, they scroll. If they don't, they paste the install command and try it.
Schritt 2: One-sentence purpose, the highest-leverage line
Two examples:
Bad (most READMEs):
An MCP server that provides tools for managing notes.
Good:
Save and search across your Claude conversations from any IDE, your AI keeps context across Code, Desktop, Cursor, and Codex.
The bad version describes the implementation. The good version describes the outcome the user gets. Guess which one converts.
Test: read your one-liner aloud. Would a stranger know whether they want this thing? If "uhh, depends", rewrite.
Schritt 3: The install command, copy-paste, complete, no edits
## Install
\`\`\`bash
claude mcp add your-server -s user -- npx -y your-mcp-server
\`\`\`
That's it. Open Claude Code and \`your-server\` is available.
Three rules:
- Single command, not a procedure. If your install needs more than one command, redesign the install.
- No placeholders to fill in.
$YOUR_API_KEY,<config-path>, "edit your config", all friction. Use sensible defaults. - Show what works for Claude Code first. It's the most common entry point in 2026. Add Cursor / Desktop / Codex variants below if they differ.
For SaaS / hosted servers (no install, just paste a URL):
## Install
In Claude Desktop: Settings → Connectors → Add custom connector → URL `https://your-mcp.io/mcp`
First call triggers magic-link sign-in. Done.
Schritt 4: Tools list, the "is it useful for me" check
After install, visitors want to know what they can actually do. Use a table:
## Tools
| Tool | What it does |
|---|---|
| \`note_save\` | Save a note. Optionally tag it. |
| \`note_search\` | Full-text search across your notes. |
| \`note_list\` | List recent notes. |
| \`note_delete\` | Delete a note by ID. |
Four columns is too many, they wrap. Two columns max. Rows order: most-used first.
Don't list every tool with its full input schema, that's academy_get_recipe territory. Visitors want gist, not spec.
Schritt 5: Configuration, where 80% of READMEs go wrong
Two failure modes:
Failure mode 1: Configuration section before the tools section. Visitor sees "configure these 12 environment variables before you can use the server" and bounces.
Failure mode 2: No reasonable defaults. Every option is required + opaque. "Set MCP_PROXY_TIMEOUT (default: none)".
Fix: defaults should work for 80% of users. Document only what they'll override.
## Configuration
For most users, no configuration needed. The defaults work.
If you want to override:
| Variable | Default | Purpose |
|---|---|---|
| \`NOTE_DB_PATH\` | \`~/.your-server/notes.db\` | Where to store notes (SQLite). |
| \`LOG_LEVEL\` | \`info\` | Set to \`debug\` for verbose logs. |
Two variables. Both have defaults. That's enough.
Schritt 6: One link to deeper docs
Most READMEs try to be the full docs. Bad idea, they become unreadable.
Instead:
## More
- [Full documentation](https://docs.your-mcp.io)
- [Examples](./examples/)
- [Architecture overview](./docs/architecture.md)
- [Contributing](./CONTRIBUTING.md)
- [Security policy](./SECURITY.md)
Anyone who needs deeper info clicks. The README stays scannable.
cat package.json 2>/dev/null | python3 -c "import json,sys; p=json.load(sys.stdin); deps=list((p.get(\"dependencies\") or {}).keys()); print(\"sdk:\", \"@modelcontextprotocol/sdk\" in deps); print(\"bin:\", bool(p.get(\"bin\"))); print(\"main:\", bool(p.get(\"main\")))" 2>/dev/null || echo "no package.json in cwd"Schritt 7: Demo (if visual)
A 10-second GIF or screenshot is worth ~200 words of description.
## Demo
For non-visual servers (most), skip this. A demo of "notes get saved" is just text.
For visual servers (browser automation, image generation, dashboards), the demo is the killer feature, put it above the tools list.
Schritt 8: The signature at the bottom
---
Built by [your-name](https://your-link). MIT licensed. Issues + PRs welcome.
One line. Says who built it (trust signal), the license (trust signal), that maintenance is active. Done.
Don't add a "Sponsors", "Acknowledgments", "Roadmap" section unless the project is mature enough to need them. They make small projects look bloated.
Schritt 9: What to delete
Common README sections that hurt conversion:
- Long architecture / "How it works" first, visitors don't care until they're already convinced.
- TOC for a 200-line README, premature, looks corporate.
- "Why I built this" personal story, saves for blog post, not README.
- Comparison tables vs competitors, feels defensive, drives visitors to the competitor's repo.
- Installation troubleshooting upfront, implies install often fails. Move to FAQ at bottom or separate doc.
- Marketing fluff, "lightning-fast", "robust", "enterprise-grade". Empty signal.
If you delete these and the README gets shorter, your conversion goes up.
Schritt 10: Verify
Run academy_validate_step. The validator confirms package.json is wired.
For the README quality, the only test that matters: show it to someone who hasn't seen the project. Watch them scroll. If they ask "what does this do?" while scrolling past the one-liner, your one-liner is bad. If they install it without scrolling past the install command, you nailed it.
If you don't have a test reader, the next-best thing is to read your README cold the next morning. Yesterday's clarity often turns out to be confusion.
Common traps
- Install command not in the first screen, you lose 40% of installs to scroll fatigue.
- Generic one-sentence ("MCP server for X"), visitor can't decide if it's relevant.
- Required env vars before any tool works, install friction, visitor bounces.
- No badges, looks abandoned even if it isn't.
- No demo for visual server, the killer feature is invisible.
- Long acknowledgments / sponsors / roadmap before content, corporate-bloat smell.
- Marketing-speak ("revolutionary", "enterprise-grade"), every visitor's BS detector goes off.
- Inconsistent install commands across IDEs, pick the most common (Claude Code), show that, add others as variants.
What good looks like
A reviewer lands on your README, scans 6 lines, copies the install command, runs it, sends one message in Claude, sees a tool call work. They star the repo. Total time: under 60 seconds.
Optimize for that visitor and the rest of the README falls into place. Everything that doesn't help that visitor's 60-second decision is dead weight.