https://github.com/stacklok/toolhive-registry
ToolHive's registry of MCP servers
https://github.com/stacklok/toolhive-registry
Last synced: 14 days ago
JSON representation
ToolHive's registry of MCP servers
- Host: GitHub
- URL: https://github.com/stacklok/toolhive-registry
- Owner: stacklok
- License: apache-2.0
- Created: 2025-08-11T09:44:01.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-12-22T17:59:05.000Z (about 1 month ago)
- Last Synced: 2025-12-22T22:02:58.755Z (about 1 month ago)
- Language: Go
- Size: 146 MB
- Stars: 12
- Watchers: 2
- Forks: 6
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.MD
Awesome Lists containing this project
README
# ToolHive Registry
This repository contains the registry of MCP (Model Context Protocol) servers available for ToolHive. Each server entry provides AI assistants with specialized tools and capabilities.
## What is this?
Think of this as a catalog of tools that AI assistants can use. Each entry in this registry represents a server that provides specific capabilities—like interacting with GitHub, querying databases, or fetching web content.
## How to Add Your MCP Server
Adding your MCP server to the registry is simple! You just need to create a YAML file with some basic information about your server. We support two types of MCP servers:
1. **Container-based servers** - Run as Docker containers
2. **Remote servers** - Accessed via HTTP/HTTPS endpoints
### Step 1: Create a Folder
Create a new folder in the `registry/` directory with your server's name (use lowercase and hyphens):
```
registry/
└── my-awesome-server/
└── spec.yaml
```
### Step 2: Create Your spec.yaml File
Choose the appropriate format based on your server type:
#### For Container-based Servers
Create a `spec.yaml` file with this minimum information:
```yaml
# Required fields - you must provide these
image: docker.io/myorg/my-server:latest # Your Docker image
description: What your server does in one sentence
transport: stdio # How your server communicates (usually "stdio")
tier: Community # "Official" or "Community"
status: Active # "Active" or "Deprecated"
tools:
- tool_name_1 # List the tools your server provides
- tool_name_2 # Or use "set_during_runtime" if tools aren't knowable up-front
# Recommended fields - helps users understand your server
repository_url: https://github.com/myorg/my-server # Where to find your code
```
#### For Remote Servers
Create a `spec.yaml` file with this minimum information:
```yaml
# Required fields - you must provide these
url: https://api.example.com/mcp # Your MCP server endpoint
description: What your server does in one sentence
transport: streamable-http # Remote servers use "streamable-http" (preferred) or "sse" (not "stdio")
tier: Community # "Official" or "Community"
status: Active # "Active" or "Deprecated"
tools:
- tool_name_1 # List the tools your server provides
- tool_name_2 # Or use "set_during_runtime" if tools aren't knowable up-front
# Recommended fields - helps users understand your server
repository_url: https://github.com/myorg/my-server # Where to find your code
```
### Step 3: Add More Details (Optional but Recommended)
You can add more information to help users:
```yaml
# ... required fields above ...
# Tell users what environment variables they need
env_vars:
- name: API_KEY
description: Your API key from example.com
required: true
secret: true # Mark sensitive data
- name: TIMEOUT
description: Request timeout in seconds
required: false
default: "30"
# Help users find your server
tags:
- api
- integration
- productivity
# Server classification
tier: Community # or "Official" if maintained by the protocol team
status: Active # or "Deprecated"
```
### Real Examples
#### Container-based Server Example
```yaml
image: ghcr.io/github/github-mcp-server:v0.10.0
description: Provides integration with GitHub's APIs for repository management
transport: stdio
repository_url: https://github.com/github/github-mcp-server
tools:
- create_issue
- create_pull_request
- get_file_contents
- search_repositories
env_vars:
- name: GITHUB_PERSONAL_ACCESS_TOKEN
description: GitHub personal access token with appropriate permissions
required: true
secret: true
tags:
- github
- version-control
- api
tier: Official
status: Active
```
#### Remote Server Example
```yaml
url: https://api.example.com/mcp/v1
description: Provides access to Example API services via MCP
transport: streamable-http
repository_url: https://github.com/example/mcp-server
tools:
- fetch_data
- process_request
- submit_job
# Authentication headers for remote servers
headers:
- name: X-API-Key
description: API key for authentication
required: true
secret: true
# OAuth configuration (alternative to headers)
oauth_config:
issuer: https://auth.example.com
client_id: mcp-client
scopes:
- read
- write
tags:
- api
- remote
- cloud
tier: Community
status: Active
```
## Common Questions
### What is "transport"?
This tells ToolHive how to communicate with your server:
For **container-based servers**:
- `stdio` - Standard input/output (most common)
- `sse` - Server-sent events
- `streamable-http` - HTTP streaming
For **remote servers**:
- `streamable-http` - HTTP streaming (recommended)
- `sse` - Server-sent events (deprecated but still supported)
- **Note:** Remote servers cannot use `stdio`
If you're not sure, use `stdio` for containers and `streamable-http` for remote servers.
**Important:** For container servers using `streamable-http` or `sse` transport, you must also specify the `target_port` field.
### What is "tier"?
- `Official` - Maintained by the MCP team or platform owners
- `Community` - Created and maintained by the community (most servers)
### What is "status"?
- `Active` - Fully functional and maintained
- `Deprecated` - No longer maintained, will be removed
### What about the "tools" field?
List all the tools your server provides. If your server's tools aren't knowable until runtime (for example, if they're dynamically generated based on configuration), you can use `"set_during_runtime"` as the value instead of listing specific tool names.
### Do I need a Docker image?
**For container-based servers:** Yes. Your MCP server must be packaged as a Docker image and published to a registry like:
- Docker Hub (`docker.io/username/image`)
- GitHub Container Registry (`ghcr.io/username/image`)
- Other public registries
**For remote servers:** No. You just need to provide the URL endpoint where your MCP server is accessible.
### Security Note: Filesystem Permissions
**Important:** Don't specify filesystem paths or volume mounts in your registry entries. Mounting host directories is a security risk and should be configured by users at runtime, not in registry specs. Only network permissions (allowed hosts and ports) should be specified in the `permissions` section.
### How do I test my entry?
After adding your entry, you can validate it:
```bash
# If you have the build tools installed
task validate
```
Or submit a pull request and our automated checks will validate it for you.
## Submitting Your Entry
1. Fork this repository
2. Add your server entry as described above
3. Submit a pull request
4. We'll review and merge your addition
### Registry Inclusion Criteria
We evaluate submissions based on several criteria to ensure quality and usefulness for the community. Your server should:
- Provide clear value and unique capabilities
- Be well-documented with accurate tool descriptions
- Follow security best practices
- Be actively maintained with recent updates
For detailed evaluation criteria, see the [Registry Criteria documentation](https://docs.stacklok.com/toolhive/concepts/registry-criteria).
### Before Submitting, Please Ensure
For **container-based servers**:
- [ ] Your Docker image is publicly accessible
- [ ] The `description` clearly explains what your server does
- [ ] You've listed all the tools your server provides
- [ ] Any required environment variables are documented
- [ ] Your server works with ToolHive
For **remote servers**:
- [ ] Your server endpoint is publicly accessible
- [ ] The `description` clearly explains what your server does
- [ ] You've listed all the tools your server provides
- [ ] Any required authentication (headers/OAuth) is documented
- [ ] The transport is set to `streamable-http` (preferred) or `sse` (not `stdio`)
- [ ] Your server works with ToolHive's proxy command
## Need Help?
- Check existing entries in the `registry/` folder for examples
- Open an issue if you have questions
- Join our community discussions
## For Maintainers
If you need to work with the registry programmatically:
```bash
# Import existing registry
task import
# Validate all entries
task validate
# Build the registry.json
task build:registry
# See all available commands
task
```
## License
Apache License 2.0