Skip to main content

Install ToolHive

This guide walks you through installing, upgrading, and managing the ToolHive CLI (thv).

Prerequisites​

Before installing ToolHive, make sure your system meets these requirements:

  • Operating systems: macOS, Linux, or Windows
  • Container runtime: Docker or Podman

ToolHive requires minimal CPU, memory, and disk space. The exact requirements depend on how many MCP servers you run and what resources they use.

Install ToolHive​

You can install ToolHive using several methods:

Homebrew is the easiest installation method on macOS or Linux:

brew tap stacklok/tap
brew install thv

Verify your installation​

To verify that ToolHive is installed correctly:

thv version

You should see output showing the version number, build date, and Git commit:

ToolHive version output
ToolHive v0.0.33
Commit: e8efa1b1d7b0776a39339257d30bf6c4a171f2b8
Built: 2025-05-12 14:31:06 UTC
Go version: go1.24.1
Platform: darwin/arm64

Upgrade ToolHive​

ToolHive automatically checks for updates and notifies you when a new version is available. When you run a ToolHive command, it displays a message if an update exists.

To upgrade ToolHive:

If you installed ToolHive via Homebrew, upgrade it with:

brew upgrade thv

Get help with ToolHive commands​

ToolHive has built-in help for all commands:

# General help
thv --help

# Help for a specific command
thv <command> --help

For detailed documentation on each command, see the CLI reference documentation.

Enable shell completion​

ToolHive can generate auto-completion scripts for your shell to make it easier to use. The thv completion command generates scripts for bash, zsh, fish, and PowerShell.

Each shell has different requirements for where to store completion scripts and how to enable them. The help output for each shell provides specific instructions:

# Get help on completion options
thv completion --help

# Get specific instructions for your shell
thv completion bash --help
thv completion zsh --help
thv completion fish --help
thv completion powershell --help

Uninstall ToolHive​

To uninstall ToolHive:

  1. First, remove any MCP servers managed by ToolHive:

    # List running servers
    thv list
    # Stop and remove each server
    thv stop --all
    thv rm <server-name>

  2. Remove all ToolHive configuration and log files:

    # Remove the secrets encryption password entry from your OS keyring
    thv secret reset-keyring

    # Delete the ToolHive configuration and log files
    # macOS:
    rm -rf ~/Library/Application\ Support/toolhive/
    # Linux:
    rm -rf ~/.config/toolhive/
    # Windows:
    Remove-Item "$env:LOCALAPPDATA\toolhive" -Recurse -Force

  3. Remove the ToolHive CLI:

If you installed ToolHive via Homebrew, uninstall it with:

brew uninstall thv

Next steps​

Now that you have ToolHive installed, you can start using it to run and manage MCP servers. See Explore the registry and Run MCP servers to get started.

Troubleshooting​

Permission denied errors​

If you see "permission denied" errors when running ToolHive:

  1. Make sure the binary is executable:

    chmod +x /path/to/thv

  2. If using Docker on Linux, make sure your user has permission to access the Docker socket:

    sudo usermod -aG docker $USER

    (Log out and back in or run newgrp docker for this to take effect)

    See Docker documentation for more details.

Upgrade error on Windows​

If you encounter an error when upgrading ToolHive on Windows, it may be due to the ToolHive executable being locked by a running MCP server proxy.

Error example
An unexpected error occurred while executing the command:
remove: Access is denied.: "C:\Users\USERNAME\AppData\Local\Microsoft\WinGet\Packages\stacklok.thv_Microsoft.Winget.Source_8wekyb3d8bbwe\thv.exe"
Uninstall failed with exit code: 0x8a150003 : Executing command failed

To resolve this:

  1. Stop all running MCP servers:

    thv stop --all

  2. After stopping all servers, run the upgrade command again:

    winget upgrade stacklok.thv

  3. If you still encounter issues, check if any ToolHive processes are still running in the background. You can use Task Manager to end any lingering thv.exe processes.

  4. Restart your MCP servers:

    thv list --all
    thv restart <server-name>
    # repeat for each server

Other issues​

For other installation issues, check the GitHub issues page or join the Discord community.