Write MCP server documentation that ranks on Google.
Most MCP servers are invisible in search because their README answers questions nobody types. Here's how to structure docs around the queries developers actually use.
MCP server discovery happens in two places: registries and Google. Registries you mostly can't control beyond a good description. Search you can control completely — and almost nobody does, because most MCP READMEs are written for people who already found the project, not for the search queries that would bring new ones.
The queries are predictable: '{thing} mcp server', '{server} claude desktop setup', '{server} cursor config', '{server} tools list'. Documentation that ranks is documentation whose headings literally answer those queries. This guide covers the README, the tool docs, and the listing pages that act as your second search surface.
Lead with the query, not the project
The first line of your README should say what the server does in the words a searcher would use: 'MCP server for querying PostgreSQL databases from Claude, Cursor, and other MCP clients.' That sentence is your title tag on GitHub, your registry description, and the snippet Google shows. 'A blazing-fast, extensible bridge to your data' ranks for nothing.
Name the category explicitly — database, web scraping, browser automation — because category words are in nearly every discovery query. And say 'MCP server' verbatim; abbreviating to 'an MCP for X' costs you the exact-phrase match.
Structure the README around search intent
Three sections do most of the SEO work: a per-client install section, a complete tool list, and a limits/pricing section. Per-client setup matters because 'X mcp server cursor' and 'X mcp server claude desktop' are distinct queries — give each client its own H3 with its own config block rather than one generic snippet, and you become the answer to all of them.
# postgres-query MCP server
MCP server for querying PostgreSQL from Claude, Cursor,
and other MCP clients. Read-only by default.
## Tools
### query(sql, params) — run a read-only query, returns rows as JSON
### list_tables() — schemas, tables, and column types
## Setup
### Claude Desktop
### Claude Code
### Cursor
### VS Code (Copilot)
## Limits & pricing
Row caps, timeouts, and per-call pricing if hosted.Your tool list is content, not metadata
Each tool deserves a heading with its real name, its parameters, and one example of input and output. This is the part of MCP docs most often skipped, and it's the part that matches long-tail queries — someone searching 'mcp tool extract tables from pdf' lands on the tool heading, not your project tagline.
Keep tool names in docs identical to the names in your server's manifest. Agents and humans both search for the literal string, and a mismatch between README and runtime erodes trust in both.
Listing pages are your second ranking surface
Registry and marketplace listings often outrank GitHub READMEs for commercial-intent queries, because those pages carry stronger domain signals. Your Loomal listing is a working example: each server page ships unique meta tags, a canonical URL, and JSON-LD structured data, and once you claim the listing it publishes your live, probed tool list — content Google indexes that no README can fake.
Write the listing description as its own text rather than pasting the README intro. Duplicate text across GitHub, the registry, and marketplaces splits ranking signals across copies of the same words; distinct framing on each surface gives you multiple shots at the results page.
Maintenance signals are ranking signals
Search rewards pages that change when reality changes. Update the README when tools are added or renamed, keep a short changelog section, and date significant updates. Stale docs accumulate broken-config complaints in issues — and 'is X mcp server still maintained' threads are exactly what you don't want ranking above your own pages.
Finally, interlink: README links to the marketplace listing, listing links back to the repo and docs. Cross-surface links are how both crawlers and humans confirm the pages describe the same living project.
FAQ
Should the README and my Loomal listing have the same text?
No. Duplicated text makes the surfaces compete for the same queries with the same words. Write the listing description fresh — it targets commercial-intent searches ('best X mcp server', pricing questions) while the README targets setup and tool queries.
Do per-client setup sections really matter for SEO?
Yes — they're the highest-volume MCP queries. 'X mcp server claude desktop' and 'X mcp server cursor' are different searches with different config answers. A dedicated heading and config block per client makes you the result for each.
How does claiming my Loomal listing help search visibility?
A claimed listing publishes your server's live tool list on a page that already carries JSON-LD structured data, a canonical URL, and unique meta tags. That's indexable, automatically current content describing exactly what your server does — generated from the server itself rather than hand-maintained.
What's the single highest-impact fix for an existing README?
Rewrite the first sentence to name what the server does, the words 'MCP server', and the clients it works with. That line feeds GitHub's title and description tags and most snippets — it's the cheapest ranking improvement available.
Claim your listing, publish your tools.
Your Loomal page ships structured data and a live tool list — make it yours.