how to write an MCP server README that gets adopted
Gives the structure of an MCP server README that drives adoption: the one-line pitch, a 30-second quickstart, tool list, and troubleshooting. Use when publishing an MCP server; not for internal-only servers or when the registry listing is the main discovery path.
TL;DR
Developers decide in 30 seconds whether to try an MCP server; the README is the trial. A working quickstart beats a features list every time. Applies to any MCP server published for others to use.
The query
how to write an MCP server README that gets adoptedUse this when
- You are publishing an MCP server for others to use.
- Developers decide in seconds whether to try it.
- The README is the main trial experience.
Not for
- The server is internal-only (a short internal doc is enough).
- You are writing registry metadata (that is a different, shorter format).
- The server is a prototype not ready for users (mark it experimental instead).
Steps
- Open with one line: what the server does and for whom.
Expected output: A pitch a developer can repeat from memory.
- Add a 30-second quickstart: install command, config snippet, and one example tool call.
Expected output: A quickstart a new user can complete without reading further.
- Document every tool with its inputs, outputs, and one example.
Expected output: A tool reference that answers questions before they are asked.
- Close with troubleshooting for the three most common setup failures.
Expected output: A README that resolves the failures users actually hit.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_p1BbswVINuU7RxPSnQ01lA