mcp-registry（MCP registry 搜索）

MCPCentral - MCP Server Discovery

Discover and search MCP servers using two real data sources:

1. Official MCP Registry (registry.modelcontextprotocol.io) — canonical source for server metadata, versions, packages, transport config, and environment variables. Public, no auth required.
2. MCPCentral (mcpcentral.io) — enrichment data: GitHub stars, npm downloads, editorial picks. Paginated bulk endpoint.

Gotchas

• Server names contain / and must be URL-encoded. Names like io.github.owner/server-name must be encoded as io.github.owner%2Fserver-name in URL path segments. Forgetting this causes 404 "Endpoint not found" errors.
• cursor vs next_cursor naming inconsistency. The MCPCentral API accepts a cursor query parameter for pagination, but the response field containing the next token is named next_cursor. These are different names for input and output.
• MCPCentral has no search parameter. The mcpcentral.io/api/servers endpoint only supports paginated browsing sorted by stars. Use the official registry for keyword search.
• title and websiteUrl may be null. Fall back to name for display and repository.url for linking when these fields are absent.
• MCPCentral enrichment data may lag the official registry. Always use the official registry for authoritative version and package data; treat MCPCentral metrics as supplemental.

Important: What the Registry Contains (and Doesn't)

Contains: Package metadata (npm/pypi/docker identifiers), install commands, transport configuration (stdio/SSE/streamable-http), environment variables, remote URLs, repository links, version history.

Does NOT contain: Tool schemas, tool lists, or runtime behavior. The registry stores *how to install and connect* to a server, not *what tools it exposes*.

To discover a server's actual tools: Install it and call tools/list via MCP protocol, or read its README/documentation.

API Reference

All endpoints are public. No authentication required.

Official Registry Endpoints

Search servers:

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=QUERY&limit=N&version=latest"

Parameters: search (substring match on name/description), limit (results per page, default 100), cursor (pagination token from previous response), updated_since (ISO 8601 datetime), version=latest (only latest versions).

Get specific server version:

curl "https://registry.modelcontextprotocol.io/v0.1/servers/SERVER_NAME_URL_ENCODED/versions/latest"

The server name contains a / (e.g., io.github.owner/server-name), so it must be URL-encoded as %2F in the path. Example: io.github.Digital-Defiance%2Fmcp-filesystem.

List all versions:

curl "https://registry.modelcontextprotocol.io/v0.1/servers/SERVER_NAME_URL_ENCODED/versions"

MCPCentral Endpoint

Browse servers with enrichment data:

curl "https://mcpcentral.io/api/servers?limit=N&cursor=TOKEN"

Returns servers sorted by stars (descending). Response includes: count (total), limit, next_cursor (base64 pagination token), servers[]. No search parameter — use for browsing popular servers or enriching data from the official registry.

Note: The pagination query parameter is cursor, but the response field containing the next token is next_cursor.

Capabilities

Searching for Servers

Use the official registry search endpoint. The search is a substring match on server names and descriptions — it is not NLP or semantic search.

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=postgres&limit=5&version=latest"

Parse the response: Each result is in servers[].server with fields: name, description, version, repository.url, packages[], remotes[]. Metadata is in servers[]._meta["io.modelcontextprotocol.registry/official"] with status, publishedAt, updatedAt, isLatest.

Pagination: If metadata.nextCursor is present, pass it as cursor to get the next page.

Fallback strategies for few/no results:

• Try shorter or alternative keywords (e.g., "db" instead of "database")
• Try the package name (e.g., "mcp-server-sqlite" instead of "sqlite tool")
• Browse recent servers without a search term

Getting Server Details

Fetch the latest version of a specific server by name:

curl "https://registry.modelcontextprotocol.io/v0.1/servers/io.github.owner%2Fserver-name/versions/latest"

Key fields to extract from the response:

• server.name — canonical identifier
• server.title — human-readable display name (may be null)
• server.description — what it does
• server.version — current version
• server.repository.url — source code link
• server.websiteUrl — project homepage (may be absent)
• server.packages[] — install methods, each with:

- registryType (npm, pypi, docker) - identifier (package name) - transport.type (stdio, sse, streamable-http) - environmentVariables[] (name, description, isRequired, isSecret) - runtimeHint (e.g., "node", "python", "uvx") - runtimeArguments[], packageArguments[]

• server.remotes[] — hosted endpoints (type, url, headers)
• server.icons[] — server icons (src, theme, sizes)
• _meta["io.modelcontextprotocol.registry/official"].status — active, deprecated, or deleted
• _meta["io.modelcontextprotocol.registry/official"].publishedAt, .updatedAt, .isLatest

Listing Versions

Get all published versions of a server:

curl "https://registry.modelcontextprotocol.io/v0.1/servers/io.github.owner%2Fserver-name/versions"

Response is servers[] array, each with full server metadata. Version status is in _meta["io.modelcontextprotocol.registry/official"] with status (active/deprecated/deleted) and isLatest (boolean).

Browsing Recent/Popular Servers

To explore without a specific search term:

Browse by recency (official registry):

curl "https://registry.modelcontextprotocol.io/v0.1/servers?limit=10&version=latest&updated_since=2026-01-01T00:00:00Z"

Browse by popularity (MCPCentral):

curl "https://mcpcentral.io/api/servers?limit=10"

Results are sorted by GitHub stars descending. Pass the next_cursor value from the response as the cursor query parameter to get the next page.

Recommending Servers (AI-Synthesized)

There is no recommendation API. To recommend servers for a user's task:

1. Extract keywords from the user's request (e.g., "I need to query a database" → search "database", "query", "sql")
2. Run multiple searches with different keywords against the official registry
3. Merge and rank results based on: description relevance, number of keyword matches, whether the server has packages (installable) vs only remotes (hosted)
4. Present as AI recommendations — clearly label these as your synthesis, not an API result

Generating Setup Guides

Extract installation and configuration from real server metadata. After fetching a server's details:

1. Determine install method from packages[]:

For registryType: "npm":

npx -y PACKAGE_IDENTIFIER

For registryType: "pypi":

uvx PACKAGE_IDENTIFIER
# or: pip install PACKAGE_IDENTIFIER && python -m PACKAGE_IDENTIFIER

For registryType: "docker":

docker run PACKAGE_IDENTIFIER

2. Extract environment variables from packages[].environmentVariables[]: List each with its name, description, and whether isRequired/isSecret.

3. Check for remote endpoints in remotes[]: If the server has remotes[], it can be used without local installation via its hosted URL.

4. Generate MCP client configuration (see "Next Steps After Discovery" below).

Reading Server Documentation

The registry does not store READMEs. To discover a server's actual tools and capabilities:

1. Extract repository.url from the server metadata
2. Construct the raw README URL:

- GitHub: https://raw.githubusercontent.com/OWNER/REPO/HEAD/README.md - If the repo has a subfolder, try: https://raw.githubusercontent.com/OWNER/REPO/HEAD/SUBFOLDER/README.md

1. Fetch and summarize the README content

This is the best way to discover what tools a server actually exposes, since the registry only stores package metadata.

MCPCentral Enrichment

Use the MCPCentral endpoint to add community metrics when presenting servers to users:

curl "https://mcpcentral.io/api/servers?limit=100"

Enrichment fields per server:

• stars — GitHub stars count
• npm_weekly_downloads — npm download volume
• npm_license — package license
• recommended — MCPCentral editorial recommendation (boolean or null)
• admin_favorite — MCPCentral staff pick (boolean or null)
• official — officially maintained (boolean or null)
• owner.name, owner.avatar_url — author info

When to use: When a user wants to compare servers by popularity, or when browsing for well-maintained options. Match servers between the two sources using the name field (format: io.github.owner/server-name).

Note: MCPCentral has no search parameter. To find a specific server's enrichment data, fetch pages and filter client-side by name, or use it for popularity-sorted browsing.

Next Steps After Discovery

After a user finds a server, provide setup configuration for their MCP client. Generate these from the server's real packages[], remotes[], and environmentVariables[] data.

For stdio-based servers (local install)

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "SERVER_NAME": {
      "command": "npx",
      "args": ["-y", "PACKAGE_IDENTIFIER"],
      "env": {
        "ENV_VAR_NAME": "your-value-here"
      }
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "SERVER_NAME": {
      "command": "npx",
      "args": ["-y", "PACKAGE_IDENTIFIER"],
      "env": {
        "ENV_VAR_NAME": "your-value-here"
      }
    }
  }
}

Generic (.mcp.json / mcp.json):

{
  "mcpServers": {
    "SERVER_NAME": {
      "command": "npx",
      "args": ["-y", "PACKAGE_IDENTIFIER"],
      "env": {
        "ENV_VAR_NAME": "your-value-here"
      }
    }
  }
}

Adapt the command and args based on registryType:

• npm: "command": "npx", "args": ["-y", "IDENTIFIER"]
• pypi: "command": "uvx", "args": ["IDENTIFIER"]
• docker: "command": "docker", "args": ["run", "-i", "--rm", "IDENTIFIER"]

If the package has runtimeHint or runtimeArguments, use those to build the command instead.

For remote servers (hosted endpoint)

If the server has remotes[] entries, provide the URL-based config:

{
  "mcpServers": {
    "SERVER_NAME": {
      "url": "REMOTE_URL",
      "transport": "sse"
    }
  }
}

Use the remotes[].type to set the transport (sse, streamable-http).

Required environment variables

Always list any environment variables from packages[].environmentVariables[], noting which are required and which are secrets. Example:

Required environment variables: - DATABASE_URL (required) — PostgreSQL connection string - API_KEY (required, secret) — Authentication token

Error Handling

404 "Endpoint not found": The server name must be URL-encoded. The / in names like io.github.owner/repo must be encoded as %2F.

Empty search results: Try shorter keywords, alternative terms, or browse without a search term. The search is substring-based, not fuzzy.

Rate limiting: The official registry is public with generous limits. If you encounter rate limits, add a brief pause between requests.

Stale MCPCentral data: The MCPCentral bulk endpoint may lag behind the official registry. Always prefer the official registry for version and package data; use MCPCentral only for enrichment metrics.

Limitations

• No tool schemas in the registry. The registry stores package/install metadata only. To see what tools a server exposes, read its README or install it and call tools/list.
• Search is substring-based. The official registry search matches substrings in name and description fields. It does not support semantic/NLP search, relevance scoring, or category filtering.
• MCPCentral has no search. The MCPCentral endpoint returns servers sorted by stars with pagination, but has no search parameter.
• Server names must be URL-encoded in path parameters since they contain /.