A community driven registry service for Model Context Protocol (MCP) servers.
This project is being built in the open and is currently in the early stages of development. Please see the overview discussion for the project scope and goals.
Use Discussions to propose and discuss product and/or technical requirements.
Use Issues to track well-scoped technical work that the community agrees should be done at some point.
Open Pull Requests when you want to contribute work towards an Issue, or you feel confident that your contribution is desireable and small enough to forego community discussion at the requirements and planning levels.
The MCP Registry service provides a centralized repository for MCP server entries. It allows discovery and management of various MCP implementations with their associated metadata, configurations, and capabilities.
- RESTful API for managing MCP registry entries (list, get, create, update, delete)
- Health check endpoint for service monitoring
- Support for various environment configurations
- Graceful shutdown handling
- MongoDB and in-memory database support
- Comprehensive API documentation
- Pagination support for listing registry entries
- Seed data export/import composability with HTTP support
- Registry instance data sharing via HTTP endpoints
- Go 1.24.x (required - check with
go version
) - MongoDB
- Docker (optional, but recommended for development)
For development:
- golangci-lint v2.3.1 - Install with:
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.3.1
The easiest way to get the registry running is uses docker compose. This will setup the MCP Registry service, import the seed data and run MongoDB in a local Docker environment.
# Run the registry and MongoDB with docker compose
make dev-compose
This will start the MCP Registry service and MongoDB with Docker, running at localhost:8080
.
If you prefer to run the service locally without Docker, you can build and run it directly:
# Build a registry executable
make build
This will create the registry
binary in the current directory. You'll need to have MongoDB running locally or with Docker.
To run the service locally:
# Run registry locally (requires MongoDB)
make dev-local
By default, the service will run on localhost:8080
.
To build the CLI tool for publishing MCP servers to the registry:
# Build the publisher tool
make publisher
To see all available make targets:
make help
Key development commands:
# Development
make dev-compose # Start development environment with Docker Compose
make dev-local # Run registry locally (requires MongoDB)
# Build targets
make build # Build the registry application
make publisher # Build the publisher tool
# Testing
make test-unit # Run unit tests with coverage report
make test-integration # Run integration tests
make test-endpoints # Test API endpoints (requires running server)
make test-publish # Test publish endpoint (requires BEARER_TOKEN)
make test-all # Run all tests
# Code quality
make lint # Run linter (same as CI)
make lint-fix # Run linter with auto-fix
# Validation
make validate-schemas # Validate JSON schemas
make validate-examples # Validate examples against schemas
make validate # Run all validation checks
# Combined workflows
make check # Run all checks (lint, validate, unit tests)
# Utilities
make clean # Clean build artifacts and coverage files
The project uses golangci-lint with extensive checks. Always run linting before pushing:
# Run all linters (same as CI)
make lint
# Run linter with auto-fix
make lint-fix
To automatically run linting before commits:
git config core.hooksPath .githooks
This will prevent commits that fail linting or have formatting issues.
├── api/ # OpenApi specification
├── cmd/ # Application entry points
├── config/ # Configuration files
├── internal/ # Private application code
│ ├── api/ # HTTP server and request handlers (routing)
│ ├── auth/ # GitHub OAuth integration
│ ├── config/ # Configuration management
│ ├── database/ # Data persistence abstraction (MongoDB and in-memory)
│ ├── model/ # Data models and domain structures
│ └── service/ # Business logic implementation
├── pkg/ # Public libraries
├── scripts/ # Utility scripts
└── tools/ # Command line tools
└── publisher/ # Tool to publish MCP servers to the registry
- HTTP requests enter through router (
internal/api/router/
) - Handlers in
internal/api/handlers/v0/
validate and process requests - Service layer executes business logic
- Database interface handles persistence
- JSON responses returned to clients
- Database Interface (
internal/database/database.go
) - Abstracts data persistence with MongoDB and memory implementations - RegistryService (
internal/service/service.go
) - Business logic abstraction over database - Auth Service (
internal/auth/auth.go
) - GitHub OAuth token validation
Publishing requires GitHub OAuth validation:
- Extract bearer token from Authorization header
- Validate token with GitHub API
- Verify repository ownership matches token owner
- Check organization membership if applicable
- Factory Pattern for service creation with dependency injection
- Repository Pattern for database abstraction
- Context Pattern for timeout management (5-second DB operations)
- Cursor-based Pagination using UUIDs for stateless pagination
GET /v0/swagger/index.html
The API is documented using Swagger/OpenAPI. This page provides a complete reference of all endpoints with request/response schemas and examples, and allows you to test the API directly from your browser.
The service can be configured using environment variables:
Variable | Description | Default |
---|---|---|
MCP_REGISTRY_APP_VERSION |
Application version | dev |
MCP_REGISTRY_DATABASE_TYPE |
Database type | mongodb |
MCP_REGISTRY_COLLECTION_NAME |
MongoDB collection name | servers_v2 |
MCP_REGISTRY_DATABASE_NAME |
MongoDB database name | mcp-registry |
MCP_REGISTRY_DATABASE_URL |
MongoDB connection string | mongodb://localhost:27017 |
MCP_REGISTRY_GITHUB_CLIENT_ID |
GitHub App Client ID | |
MCP_REGISTRY_GITHUB_CLIENT_SECRET |
GitHub App Client Secret | |
MCP_REGISTRY_LOG_LEVEL |
Log level | info |
MCP_REGISTRY_SEED_FROM |
Path or URL to import seed data (supports local files and HTTP URLs) | data/seed.json |
MCP_REGISTRY_SERVER_ADDRESS |
Listen address for the server | :8080 |
Pre-built Docker images are automatically published to GitHub Container Registry on each release and main branch commit:
# Run latest from main branch
docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:latest
# Run specific commit build
docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main-20250806-a1b2c3d
Available image tags:
latest
- Latest commit from main branchmain-<date>-<sha>
- Specific commit builds
Configuration: The Docker images support all environment variables listed in the Configuration section. For production deployments, you'll need to configure the database connection and other settings via environment variables.
Registry instances can import data from:
Local files:
MCP_REGISTRY_SEED_FROM=data/seed.json ./registry
HTTP endpoints:
MCP_REGISTRY_SEED_FROM=http://other-registry:8080 ./registry
Run the test script to validate API endpoints:
./scripts/test_endpoints.sh
You can specify specific endpoints to test:
./scripts/test_endpoints.sh --endpoint health
./scripts/test_endpoints.sh --endpoint servers
See the LICENSE file for details.