{"id":27491195,"url":"https://github.com/StacklokLabs/toolhive","last_synced_at":"2025-04-16T22:02:00.844Z","repository":{"id":286963823,"uuid":"947349598","full_name":"StacklokLabs/toolhive","owner":"StacklokLabs","description":"Run and manage MCP servers easily and securely","archived":false,"fork":false,"pushed_at":"2025-04-09T08:02:59.000Z","size":3402,"stargazers_count":17,"open_issues_count":15,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-09T15:18:15.312Z","etag":null,"topics":["ai","ai-security","aicodeassistant","golang","kubernetes","mcp","mcp-security","mcp-servers","mcp-tools","security"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StacklokLabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.MD","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-12T14:49:15.000Z","updated_at":"2025-04-09T15:02:40.000Z","dependencies_parsed_at":"2025-04-09T08:46:27.132Z","dependency_job_id":null,"html_url":"https://github.com/StacklokLabs/toolhive","commit_stats":null,"previous_names":["stackloklabs/toolhive"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StacklokLabs%2Ftoolhive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StacklokLabs%2Ftoolhive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StacklokLabs%2Ftoolhive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StacklokLabs%2Ftoolhive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StacklokLabs","download_url":"https://codeload.github.com/StacklokLabs/toolhive/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249280666,"owners_count":21243142,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-security","aicodeassistant","golang","kubernetes","mcp","mcp-security","mcp-servers","mcp-tools","security"],"created_at":"2025-04-16T22:01:00.751Z","updated_at":"2025-04-16T22:02:00.800Z","avatar_url":"https://github.com/StacklokLabs.png","language":"Go","funding_links":[],"categories":["📦 \u003ca name=\"data-platforms\"\u003e\u003c/a\u003eData Platforms","Tools","🧑‍🚀 Tools and code","🧑‍🎨 \u003ca name=\"art-literature\"\u003e\u003c/a\u003eArt \u0026 Literature","Frameworks","Utilities","📦 Other","MCP Servers \u0026 Protocol","MCP Servers"],"sub_categories":["Server Managers","Supply Chain","Community","Development Tools","Cloud \u0026 DevOps"],"readme":"# ToolHive - making MCP servers easy and secure \u003c!-- omit in toc --\u003e\n\n[![Release](https://img.shields.io/github/v/release/StacklokLabs/toolhive?style=flat\u0026label=Latest%20version)](https://github.com/StacklokLabs/toolhive/releases)\n|\n[![CI](https://github.com/StacklokLabs/toolhive/actions/workflows/run-on-main.yml/badge.svg?event=push)](https://github.com/StacklokLabs/toolhive/actions/workflows/run-on-main.yml)\n|\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache2.0-brightgreen.svg?style=flat)](https://opensource.org/licenses/Apache-2.0)\n|\n[![Star on GitHub](https://img.shields.io/github/stars/StacklokLabs/toolhive.svg?style=flat\u0026logo=github\u0026label=Stars)](https://github.com/StacklokLabs/toolhive)\n|\n[![Discord](https://img.shields.io/discord/1184987096302239844?style=flat\u0026logo=discord\u0026label=Discord)](https://discord.gg/stacklok)\n\n\u003cimg src=\"docs/images/toolhive.png\" alt=\"ToolHive Logo\" width=\"300\" /\u003e\n\nToolHive (thv) is a lightweight utility designed to simplify the deployment and\nmanagement of MCP (Model Context Protocol) servers, ensuring ease of use,\nconsistency, and security.\n\n\u003cimg src=\"./docs/images/thv-readme-demo.svg\" alt=\"Terminal Recording\"\u003e\n\n## Contents \u003c!-- omit in toc --\u003e\n\n- [Why ToolHive?](#why-toolhive)\n  - [Key benefits](#key-benefits)\n- [Getting started](#getting-started)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#installation)\n  - [Quickstart - run your first MCP server](#quickstart---run-your-first-mcp-server)\n- [Client compatibility](#client-compatibility)\n- [Architecture overview](#architecture-overview)\n- [Usage examples](#usage-examples)\n  - [Register clients](#register-clients)\n  - [Find and run an MCP server](#find-and-run-an-mcp-server)\n  - [Manage MCP servers](#manage-mcp-servers)\n  - [Secrets management](#secrets-management)\n  - [Run a custom MCP server](#run-a-custom-mcp-server)\n  - [Run MCP servers using protocol schemes](#run-mcp-servers-using-protocol-schemes)\n- [Advanced usage](#advanced-usage)\n  - [Customize permissions](#customize-permissions)\n  - [Run ToolHive in Kubernetes](#run-toolhive-in-kubernetes)\n- [Contributing to ToolHive](#contributing-to-toolhive)\n- [License](#license)\n\n## Why ToolHive?\n\nDeploying MCP servers often involves complex, multi-step processes that can\nintroduce friction, such as running potentially unsafe commands (e.g., uv or\nnpx), manually managing security credentials (e.g., storing API tokens in\nplaintext), and dealing with inconsistent packaging methods.\n\nToolHive aims to solve these challenges by running containers in a consistent\nand locked-down environment, granting only the minimal permissions required to\nrun. This significantly reduces the attack surface, improves usability, and\nenforces best practices for container security.\n\nToolHive simplifies MCP deployment by focusing on three key areas:\n\n- **Ease of use**: Instantly deploy MCP servers using Docker containers. Start\n  MCP servers with a single, straightforward command without the need to install\n  and manage different versions of Python, Node.js, or other build tools.\n\n- **Enhanced security**: Secure by default. ToolHive securely manages secrets\n  and configurations, greatly reducing the risk of leaks. Avoid plaintext\n  secrets in configuration files.\n\n- **Standardized packaging**: Leverage OCI container standards to provide a\n  repeatable, standardized packaging method for MCP servers, ensuring\n  compatibility and reliability.\n\n### Key benefits\n\n- **Curated MCP registry**: ToolHive provides a curated registry of MCPs with\n  verified configurations, allowing you to discover and deploy MCP servers\n  effortlessly. Simply select one from the list and run it securely with a\n  single command.\n\n- **Enterprise-ready authorization**: Robust authorization controls designed for\n  enterprise environments, securely managing tool access and integrating\n  seamlessly with existing infrastructure (e.g., Kubernetes).\n\n- **Seamless integration**: Automatic configuration of popular development tools\n  like GitHub Copilot, Cursor, and more to streamline your workflow.\n\n## Getting started\n\n### Prerequisites\n\nToolHive currently works on macOS and Linux using Docker or Podman.\n\nFor client auto-discovery/configuration, a supported client:\n\n- VS Code (v1.99.0 or newer) with an active GitHub Copilot subscription\n- Cursor\n- Roo Code (VS Code extension)\n\n### Installation\n\nToolHive is a CLI tool written in Go and packaged as a single binary. You can\ninstall it using one of the following methods:\n\n#### Download the binary \u003c!-- omit in toc --\u003e\n\nDownload the latest cross-platform release binaries from\n[toolhive/releases](https://github.com/StacklokLabs/toolhive/releases).\n\n#### Homebrew (macOS) \u003c!-- omit in toc --\u003e\n\nInstall on macOS using Homebrew:\n\n```bash\nbrew tap stacklok/tap\nbrew install thv\n```\n\n#### Build from source \u003c!-- omit in toc --\u003e\n\nTo build ToolHive from source, clone this repository and build the CLI using Go:\n\n```bash\ngo build ./cmd/thv\ngo install ./cmd/thv\n```\n\nOr using [Task](https://taskfile.dev/installation):\n\n```bash\ntask build\ntask install\n```\n\n### Quickstart - run your first MCP server\n\n\u003e Note: This example enables auto-discovery to automatically find supported\n\u003e client(s) and update their configuration. Skip this step if you prefer to\n\u003e manually configure your client, or run `thv config register-client --help` to\n\u003e learn how to explicitly register a client.\n\n```shell\n# Enable client auto-discovery:\nthv config auto-discovery true\n\n# Run the Fetch MCP server which allows LLMs to fetch the contents of a website:\nthv run fetch\n\n# List the running MCP servers:\nthv list\n```\n\nYour client should now be able to use the `fetch` MCP tool to fetch website\ncontent.\n\n## Client compatibility\n\nToolHive has been tested with the following clients:\n\n| Client            | Supported | Notes                                  |\n| ----------------- | --------- | -------------------------------------- |\n| Copilot (VS Code) | ✅        | v1.99.0+ or Insiders version           |\n| Cursor            | ✅        |                                        |\n| Roo Code          | ✅        |                                        |\n| PydanticAI        | ✅        |                                        |\n| Continue          | ❌        | Continue doesn't yet support SSE       |\n| Claude Desktop    | ❌        | Claude Desktop doesn't yet support SSE |\n\nOther clients and development libraries that support the SSE protocol can also\nbe used with ToolHive.\n\nAutomatic configuration is supported for Copilot, Cursor, and Roo Code. For\nother clients, manual configuration of the MCP server URL is required.\n\n## Architecture overview\n\nToolHive exposes an SSE proxy to forward requests to MCP servers running in\ncontainers. The proxy communicates with MCP servers via standard input/output\n(stdio) or server-sent events (SSE).\n\n```mermaid\nflowchart LR\n  subgraph container[Docker/Podman]\n    direction LR\n    proxy1[SSE proxy 1]\n    proxy2[SSE proxy 2]\n    proxy3[SSE proxy 3]\n    mcp1[MCP Server]\n    mcp2[MCP Server]\n    mcp3[MCP Server]\n\n    proxy1 --\u003e|stdio| mcp1\n    proxy2 --\u003e|stdio| mcp2\n    proxy3 --\u003e|sse| mcp3\n  end\n\n  T[ToolHive CLI] --\u003e|Socket API| container\n  C[Client] --\u003e|HTTP/SSE| proxy1\n  C[Client] --\u003e|HTTP/SSE| proxy2\n  C[Client] --\u003e|HTTP/SSE| proxy3\n```\n\n## Usage examples\n\nCommon usage scenarios are detailed below. To view all available commands and\noptions, see the [ToolHive CLI reference](./docs/cli/thv.md) or run\n`thv --help`.\n\n### Register clients\n\nToolHive can automatically configure supported clients to use the MCP servers\nyou run. To take advantage of this feature, clients must be registered before\nyou run an MCP server.\n\nTo enable automatic discovery and configuration of supported clients, run:\n\n```bash\nthv config auto-discovery true\n```\n\nOr, you can register clients manually:\n\n```bash\n# Register a client\nthv config register-client \u003cclient-name\u003e\n\n# Show registered clients\nthv config list-registered-clients\n\n# Remove a client\nthv config remove-client \u003cclient-name\u003e\n```\n\n### Find and run an MCP server\n\nFirst, find the MCP server you want to run. You can list or search available MCP\nservers in the built-in registry using:\n\n```bash\n# List all available servers\nthv registry list\n\n# Find a server by keyword\nthv search \u003csearch-term\u003e\n```\n\nTo view detailed information about a specific MCP server including its available\ntools, configuration options, and other metadata, use:\n\n```bash\nthv registry info \u003cname-of-mcp-server\u003e\n```\n\nOnce you find the MCP server you want to run, start it using the `thv run`\ncommand:\n\n```bash\nthv run \u003cname-of-mcp-server\u003e\n```\n\nThe registry already contains all the parameters needed to run the server, so\nyou don't need to specify any additional arguments. ToolHive will automatically\npull the image and start the server.\n\nWe're always looking to expand our MCP server registry. If you have a specific\nserver you'd like to see included, feel free to\n[open an issue](https://github.com/StacklokLabs/toolhive/issues) or submit a\npull request to update the [registry.json](pkg/registry/data/registry.json)\nfile.\n\n### Manage MCP servers\n\nTo list the running MCP servers:\n\n```bash\nthv list\n```\n\nThis displays all active MCP servers managed by ToolHive, along with their\ncurrent status. To include stopped servers, add the `--all` flag.\n\nTo stop and/or remove a server:\n\n```bash\nthv stop \u003cname-of-mcp-server\u003e\nthv rm \u003cname-of-mcp-server\u003e\n\n# Or to stop and remove in one command:\nthv rm -f \u003cname-of-mcp-server\u003e\n```\n\n### Secrets management\n\nMany MCP servers require API tokens or other secrets for authentication.\nToolHive provides a secure way to manage these secrets without exposing them in\nplaintext configuration files.\n\nThis example enables ToolHive's encrypted secrets store, creates a secret for a\nGitHub authentication token, and runs the GitHub MCP server with the token:\n\n```bash\nthv config secrets-provider encrypted\nthv secret set github\n# \u003center your GitHub personal access token when prompted\u003e\n\nthv run --secret github,target=GITHUB_PERSONAL_ACCESS_TOKEN github\n```\n\nToolHive stores the encryption password in your operating system's keyring\nservice.\n\nFor more details on managing secrets, see the\n[`thv secret` command reference](./docs/cli/thv_secret.md) or run\n`thv secret --help`.\n\n### Run a custom MCP server\n\nIf you want to run a custom MCP server that is not in the registry, you can do\nso by specifying the image name and any additional arguments. For example:\n\n```bash\nthv run --transport sse --name my-mcp-server --port 8080 my-mcp-server-image:latest -- my-mcp-server-args\n```\n\nThis command closely resembles `docker run` but focuses on security and\nsimplicity. When invoked:\n\n- ToolHive creates a container from the specified image\n  (`my-mcp-server-image:latest`).\n\n- It configures the container to listen on the chosen port (8080).\n\n- Labels the container so it can be tracked by ToolHive:\n\n  ```yaml\n  toolhive: true\n  toolhive-name: my-mcp-server\n  ```\n\n- Sets up the specified transport method (`--transport stdio` or\n  `--transport sse`):\n  - **Standard I/O** (`stdio`), default:\\\n    ToolHive redirects SSE traffic from the client to the container's standard input\n    and output. This acts as a secure proxy, ensuring that the container does not\n    have direct access to the network or the host machine.\n  - **Server-sent events (SSE)** (`sse`):\\\n    ToolHive creates a reverse proxy on a random port that forwards requests to the\n    container. This means the container itself does not directly expose any ports.\n\n### Run MCP servers using protocol schemes\n\nToolHive supports running MCP servers directly from package managers using protocol schemes. This allows you to run MCP servers without having to build and publish Docker images first.\n\nCurrently, two protocol schemes are supported:\n\n- **uvx://**: For Python-based MCP servers using the uv package manager\n- **npx://**: For Node.js-based MCP servers using npm\n\nFor example, to run a Python-based MCP server:\n\n```bash\nthv run uvx://awslabs.core-mcp-server@latest\n```\n\nOr to run a Node.js-based MCP server:\n\n```bash\nthv run npx://pulumi/mcp-server@latest\n```\n\nWhen you use a protocol scheme, ToolHive will:\n\n1. Detect the protocol scheme and extract the package name\n2. Generate a Dockerfile based on the appropriate template\n3. Build a Docker image with the package installed\n4. Run the MCP server using the built image\n\nNote that in this case, you still might need to specify additional arguments like the\ntransport method, volumes, and environment variables. So, the command might look like:\n\n```bash\nthv run --transport sse --name my-mcp-server --port 8080 uvx://some-sse-mcp-server@latest -- my-mcp-server-args\n```\n\nRead the documentation for the specific MCP server to see if it requires any additional\narguments.\n\n## Advanced usage\n\n### Customize permissions\n\nContainers launched by ToolHive come with a minimal set of permissions, strictly\nlimited to what is required. Permissions can be further customized via a\nJSON-based permission profile provided with the `--permission-profile` flag.\n\nAn example permission profile file could be:\n\n```json\n{\n  \"read\": [\"/var/run/mcp.sock\"],\n  \"write\": [\"/var/run/mcp.sock\"],\n  \"network\": {\n    \"outbound\": {\n      \"insecure_allow_all\": false,\n      \"allow_transport\": [\"tcp\", \"udp\"],\n      \"allow_host\": [\"localhost\", \"google.com\"],\n      \"allow_port\": [80, 443]\n    }\n  }\n}\n```\n\nThis profile lets the container read and write to the `/var/run/mcp.sock` Unix\nsocket and also make outbound network requests to `localhost` and `google.com`\non ports `80` and `443`.\n\nTwo built-in profiles are included for convenience:\n\n- `stdio`: Grants minimal permissions with no network access.\n- `network`: Permits outbound network connections to any host on any port (not\n  recommended for production use).\n\n### Run ToolHive in Kubernetes\n\nToolHive can also be used to deploy MCP servers in a Kubernetes cluster. This\nfunctionality is still under active development for production use cases, but we\ninvite you to try it out locally using a kind cluster.\n\nCheck out the\n[Run ToolHive in Kubernetes using kind](./docs/running-toolhive-in-kind-cluster.md)\nguide to get started.\n\n## Contributing to ToolHive\n\nWe welcome contributions to ToolHive! If you'd like to contribute, please review\nthe [CONTRIBUTING guide](./CONTRIBUTING.md) for details on how to get started.\n\nIf you run into a bug or have a feature request, please\n[open an issue](https://github.com/StacklokLabs/toolhive/issues) in the\nrepository or join us in the `#toolhive-developers` channel on our\n[community Discord server](https://discord.gg/stacklok).\n\n## License\n\nThis project is licensed under the Apache 2.0 License. See the\n[LICENSE](./LICENSE) file for details.\n\n\u003c!-- markdownlint-disable-file MD033 --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStacklokLabs%2Ftoolhive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FStacklokLabs%2Ftoolhive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStacklokLabs%2Ftoolhive/lists"}