go-mcp-registry

A Go SDK for the Model Context Protocol (MCP) Registry - the official registry for MCP servers.

Overview

The Model Context Protocol (MCP) enables applications to integrate with external data sources and tools. The MCP Registry serves as a central hub for discovering and retrieving MCP servers developed by the community.

This Go SDK provides an idiomatic interface to the MCP Registry API, allowing you to:

• 🔍 Discover MCP servers with search and filtering capabilities
• 📦 Retrieve server details including installation packages and configurations
• 🔄 Handle pagination automatically or manually
• ⚡ Track rate limits and handle API errors gracefully
• 🎯 Find specific versions with flexible version resolution
• 📊 Access comprehensive metadata for each server

Installation

go get github.com/leefowlercu/go-mcp-registry

Requirements: Go 1.24 or later

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/leefowlercu/go-mcp-registry/mcp"
)

func main() {
    // Create a client
    client := mcp.NewClient(nil)
    ctx := context.Background()

    // List servers
    servers, _, err := client.Servers.List(ctx, &mcp.ServerListOptions{
        ListOptions: mcp.ListOptions{Limit: 10},
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d servers:\n", len(servers.Servers))
    for _, server := range servers.Servers {
        fmt.Printf("- %s (v%s): %s\n", server.Name, server.Version, server.Description)
    }

    // Get all versions of a server by name
    gmailServers, _, err := client.Servers.ListVersionsByName(ctx, "ai.waystation/gmail")
    if err != nil {
        log.Fatal(err)
    }
    if len(gmailServers) > 0 {
        fmt.Printf("\nGmail server latest version: %s\n", gmailServers[0].Version)
    }
}

Usage Guide

Client Configuration

import (
    "net/http"
    "time"
    "github.com/leefowlercu/go-mcp-registry/mcp"
)

// Default client
client := mcp.NewClient(nil)

// Custom HTTP client with timeout
httpClient := &http.Client{
    Timeout: 60 * time.Second,
}
client := mcp.NewClient(httpClient)

Listing Servers

// Basic listing
servers, resp, err := client.Servers.List(ctx, nil)

// With search and filtering
opts := &mcp.ServerListOptions{
    Search: "github",           // Search server names
    Version: "latest",          // Only latest versions
    ListOptions: mcp.ListOptions{
        Limit: 20,              // Page size
    },
}
servers, resp, err := client.Servers.List(ctx, opts)

// Get all servers (handles pagination automatically)
allServers, _, err := client.Servers.ListAll(ctx, nil)

Getting Servers by Name

// Get all versions of a server by name
servers, _, err := client.Servers.ListVersionsByName(ctx, "ai.waystation/gmail")

// Get latest version only
server, _, err := client.Servers.GetByNameLatest(ctx, "ai.waystation/gmail")

// Get specific version
server, _, err := client.Servers.GetByNameExactVersion(ctx, "ai.waystation/gmail", "0.3.1")

// Get latest active version (uses semantic versioning)
server, _, err := client.Servers.GetByNameLatestActiveVersion(ctx, "ai.waystation/gmail")

Manual Pagination

opts := &mcp.ServerListOptions{
    ListOptions: mcp.ListOptions{Limit: 50},
}

for {
    resp, _, err := client.Servers.List(ctx, opts)
    if err != nil {
        break
    }

    // Process servers
    for _, server := range resp.Servers {
        fmt.Printf("Server: %s\n", server.Name)
    }

    // Check for more pages
    if resp.Metadata.NextCursor == "" {
        break
    }
    opts.Cursor = resp.Metadata.NextCursor
}

Error Handling

servers, resp, err := client.Servers.List(ctx, nil)
if err != nil {
    // Check for rate limiting
    if rateLimitErr, ok := err.(*mcp.RateLimitError); ok {
        fmt.Printf("Rate limited. Reset at: %v\n", rateLimitErr.Rate.Reset)
        return
    }

    // Check for API errors
    if apiErr, ok := err.(*mcp.ErrorResponse); ok {
        fmt.Printf("API error: %v\n", apiErr.Message)
        return
    }

    log.Fatal(err)
}

// Check rate limit info
if resp.Rate.Limit > 0 {
    fmt.Printf("Rate limit: %d/%d remaining\n", resp.Rate.Remaining, resp.Rate.Limit)
}

API Methods Reference

Method	Description
List(ctx, opts)	List servers with pagination and filtering
Get(ctx, serverName, opts)	Get server by name with optional version
ListAll(ctx, opts)	Get all servers (automatic pagination)
ListVersionsByName(ctx, name)	Get all versions of a server by name
ListByUpdatedSince(ctx, since)	Get servers updated since timestamp
GetByNameLatest(ctx, name)	Get latest version using API filter
GetByNameExactVersion(ctx, name, version)	Get specific version via dedicated endpoint
GetByNameLatestActiveVersion(ctx, name)	Get latest active version by semver

For detailed documentation, see the Go Reference.

Examples

This repository includes working examples in the examples/ directory:

• examples/list/ - List servers with basic options
• examples/get/ - Get server details by name
• examples/paginate/ - Manual and automatic pagination

Run examples:

go run ./examples/list/
go run ./examples/get/ "ai.waystation/gmail"
go run ./examples/paginate/

Development

Running Tests

# Unit tests
go test ./...

# With coverage
go test -cover ./...

# Integration tests (requires network)
INTEGRATION_TESTS=true go test ./test/integration/

# Specific test
go test -v ./mcp -run TestServersService_ListVersionsByName

Building

# Build all packages
go build ./...

# Build examples
go build ./examples/...

# Format code
gofmt -s -w .

# Lint
go vet ./...

Architecture

This SDK follows the service-oriented architecture pattern established by google/go-github, organizing API endpoints into logical service groups:

• Client - Main entry point with HTTP client management
• ServersService - All server-related operations

The SDK imports and reuses official types from the MCP Registry repository to ensure perfect API compatibility without type conversion overhead.

Links

• MCP Protocol: https://modelcontextprotocol.io/
• MCP Registry: https://registry.modelcontextprotocol.io/
• API Documentation: https://registry.modelcontextprotocol.io/docs
• Registry Repository: https://github.com/modelcontextprotocol/registry

License

MIT License - see LICENSE file for details.