Writing Great MCP Tool Documentation

Your README is your tool's storefront on mcpm. This guide covers writing docs that get installs.

Why Documentation Matters

On mcpm, users decide to install in seconds. They scan your README and decide:

• What does this do? (first 5 seconds)
• Is it easy to set up? (next 10 seconds)
• Can I trust it? (final 5 seconds)

If they can't answer these in 20 seconds, they move on.

The Perfect README Structure

1. Title and One-Liner (5 seconds)

# Weather MCP

Get real-time weather data and 5-day forecasts for any city worldwide.

This becomes your mcpm description. Make every word count.

2. Quick Install (5 seconds)

## Install

\`\`\`bash
mcpm-dev add weather-mcp
\`\`\`

One command. Copy-pasteable. No friction.

3. Setup (10 seconds)

## Setup

1. Get a free API key at https://openweathermap.org/api
2. Add to your MCP client config:

\`\`\`json
{
  "mcpServers": {
    "weather-mcp": {
      "command": "npx",
      "args": ["-y", "weather-mcp"],
      "env": {
        "OPENWEATHER_API_KEY": "your-key-here"
      }
    }
  }
}
\`\`\`

Show the exact config for Claude Desktop, Cursor, and Windsurf.

4. Available Tools

Document every tool with:

## Tools

### get_current_weather

Get current weather conditions for any city.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| city | string | Yes | City name |
| units | string | No | celsius (default) or fahrenheit |

**Example:**

\`\`\`
> What's the weather in Tokyo?
→ 22°C, partly cloudy, humidity 65%
\`\`\`

### get_forecast

Get 5-day weather forecast.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| city | string | Yes | City name |
| days | number | No | 1-5 (default: 3) |

5. Examples (Real Usage)

## Examples

### With Claude Desktop

> "Should I bring an umbrella to work tomorrow?"
> Claude calls get_forecast({ city: "San Francisco", days: 1 })
> → "Rain expected. Yes, bring an umbrella. ☔"

### With Cursor

> "What's the weather where our main customer is?"
> Cursor calls get_current_weather({ city: "New York" })
> → Used in the AI chat to inform a deployment decision

6. Troubleshooting

## Troubleshooting

| Problem | Solution |
|---------|----------|
| "API key invalid" | Verify key at openweathermap.org |
| "City not found" | Try "London,UK" format |
| Tool not connecting | Check client MCP logs |

7. Links

## Links

- [mcpm page](https://www.mcpm.dev/packages/weather-mcp)
- [GitHub repository](https://github.com/you/weather-mcp)
- [Report an issue](https://github.com/you/weather-mcp/issues)
- [OpenWeatherMap API docs](https://openweathermap.org/api)

Documentation Checklist

Before publishing:

• One-sentence description in first paragraph
• Copy-paste install command
• Client config examples for Claude/Cursor/Windsurf
• Every tool documented with parameters table
• Real usage examples showing agent interactions
• Troubleshooting section for common issues
• Links to mcpm, GitHub, and external docs
• Environment variables clearly listed
• Version badge or changelog link

Pro Tips

• Use emoji sparingly — they add personality but don't overdo it
• Write for AI agents too — agents read tool descriptions to decide which tool to call
• Keep examples real — copy-paste from actual agent conversations
• Update on every publish — mcpm reads your README fresh each time

Great docs = more installs = more users = better tools. Invest the time.

#MCP #Tutorial #Documentation #mcpm #BestPractices