A Go SDK for the Model Context Protocol (MCP) Registry - the official registry for MCP servers.
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
This release includes API v0.1 migration and significant testing improvements:
- API v0.1 Support: All endpoints now use the stable v0.1 API path
- Enhanced Testing: Test coverage increased from 73.5% to 94.2%
- Version Options: Get() method now supports version-specific retrieval via ServerGetOptions
- Breaking Change: Internal endpoint migration (no code changes required for users)
For complete details, see the CHANGELOG.
go get github.com/leefowlercu/go-mcp-registryRequirements: Go 1.24 or later
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 _, serverResponse := range servers.Servers {
fmt.Printf("- %s (v%s): %s\n", serverResponse.Server.Name, serverResponse.Server.Version, serverResponse.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)
}
}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)// 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)// Get latest version using Get()
server, _, err := client.Servers.Get(ctx, "ai.waystation/gmail", nil)
// Get specific version using Get()
server, _, err := client.Servers.Get(ctx, "ai.waystation/gmail", &mcp.ServerGetOptions{
Version: "1.0.0",
})
// Get all versions of a server by name
servers, _, err := client.Servers.ListVersionsByName(ctx, "ai.waystation/gmail")
// Get latest version using name filter
server, _, err := client.Servers.GetByNameLatest(ctx, "ai.waystation/gmail")
// Get specific version via dedicated endpoint (most performant)
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")Registry metadata (Status, PublishedAt, UpdatedAt, IsLatest) is available when using List() methods:
servers, _, err := client.Servers.List(ctx, nil)
if err != nil {
log.Fatal(err)
}
for _, serverResponse := range servers.Servers {
// Access server data
fmt.Printf("Name: %s\n", serverResponse.Server.Name)
fmt.Printf("Version: %s\n", serverResponse.Server.Version)
// Access metadata (if available)
if serverResponse.Meta.Official != nil {
fmt.Printf("Status: %s\n", serverResponse.Meta.Official.Status)
fmt.Printf("Published: %v\n", serverResponse.Meta.Official.PublishedAt)
fmt.Printf("Updated: %v\n", serverResponse.Meta.Official.UpdatedAt)
fmt.Printf("Is Latest: %v\n", serverResponse.Meta.Official.IsLatest)
}
}Note: Get() methods return ServerJSON without metadata. Use List() methods to access registry metadata.
opts := &mcp.ServerListOptions{
ListOptions: mcp.ListOptions{Limit: 50},
}
for {
resp, _, err := client.Servers.List(ctx, opts)
if err != nil {
break
}
// Process servers
for _, serverResponse := range resp.Servers {
fmt.Printf("Server: %s\n", serverResponse.Server.Name)
}
// Check for more pages
if resp.Metadata.NextCursor == "" {
break
}
opts.Cursor = resp.Metadata.NextCursor
}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)
}| 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 |
ListByName(ctx, name) |
Get all versions with exact name match |
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.
This repository includes working examples in the examples/ directory:
- examples/list/ - List servers with search, filtering, and metadata access
- examples/get/ - Get server details with version options and error handling
- examples/paginate/ - Manual and automatic pagination
- examples/version/ - Version-specific retrieval using GetByNameExactVersion
- examples/updated/ - Timestamp-based filtering with ListByUpdatedSince
Run examples:
go run ./examples/list/
go run ./examples/get/ "ai.waystation/gmail"
go run ./examples/get/ "ai.waystation/gmail" "1.0.0"
go run ./examples/paginate/
go run ./examples/version/ "ai.waystation/gmail"
go run ./examples/updated/ 24Current test coverage: 94.2%
# 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# Build all packages
go build ./...
# Build examples
go build ./examples/...
# Format code
gofmt -s -w .
# Lint
go vet ./...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.
- 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
MIT License - see LICENSE file for details.