toolhive-cli-user

@stacklok · 收录于今天 · 上游提交今天

Guide for using ToolHive CLI (thv) to run and manage MCP servers and skills. Use when running, listing, stopping, building, or configuring MCP servers locally. Covers server lifecycle, registry browsing, secrets management, client registration, groups, container builds, exports, permissions, network isolation, authentication, and skill management (install, uninstall, list, info, build, push, validate). NOT for Kubernetes operator usage or ToolHive development/contributing.

场景本地服务管理技能安装 mcp配置

适合你，如果需要在本地运行和管理 MCP 服务器与技能

/ 下载安装

https://github.com/stacklok/toolhive/tree/main/skills/toolhive-cli-user ↗

/ 通过 npx 安装 校验哈希

npx oh-my-skill add stacklok/toolhive/toolhive-cli-user

/ 通过 bash 安装

curl -fsSL https://oh-my-skill.com/install.sh | bash -s -- stacklok/toolhive/toolhive-cli-user

/ 已经装过?验证本机副本,不用重装

npx oh-my-skill verify stacklok/toolhive/toolhive-cli-user

安装目标可用 --agent / --scope 或 --to 明确指定;省略时只会在唯一已存在的 agent 目录上自动选择,零命中或多命中会停止并提示。content_hash 缺失或不一致均拒装。

1947GitHub stars

~2.2K最小装载

~7.4K含声明引用

~7.4K文本包总量

索引托管

怎么用

技能原文 SKILL.md作者撰写 · Apache-2.0 · b9fcb21

ToolHive CLI User Guide

Prerequisites

Container Runtime: Docker, Podman, Colima, or Rancher Desktop (with dockerd/moby)
ToolHive CLI: Install with brew install stacklok/tap/thv (macOS/Linux) or winget install stacklok.thv (Windows)

Verify: thv version

Quick Start

thv run filesystem      # Run server from registry
thv list                # List running servers
thv status filesystem   # Detailed server info
thv logs filesystem     # View logs
thv stop filesystem     # Stop server
thv rm filesystem       # Remove server

Running MCP Servers

Five input methods: registry name, container image, protocol scheme (uvx://, npx://, go://), exported config (--from-config), or remote URL.

thv run filesystem                                          # Registry
thv run ghcr.io/github/github-mcp-server:latest -- <args>   # Container image
thv run uvx://mcp-server-git                                # Python (uvx)
thv run npx://@modelcontextprotocol/server-filesystem       # Node.js (npx)
thv run go://github.com/example/mcp-server                  # Go
thv run --from-config ./config.json                         # Exported config
thv run https://api.example.com/mcp --name my-remote        # Remote URL

For all flags, authentication options, and telemetry configuration, see [COMMANDS.md](references/COMMANDS.md#thv-run). For detailed usage patterns, see [EXAMPLES.md](references/EXAMPLES.md).

Managing Servers

thv list                          # Running servers
thv list --all                    # Include stopped
thv list --format json            # JSON output
thv list --format mcpservers      # MCP client config format
thv list --group production       # Filter by group

thv status filesystem             # Detailed server info (URL, port, transport, uptime)
thv status filesystem --format json

thv stop filesystem github        # Stop specific servers
thv stop --all                    # Stop all

thv start filesystem              # Resume stopped server
thv start --all                   # Start all stopped servers
thv start --group development     # Start all in group
thv restart filesystem            # Alias for start (backward compat)

thv rm filesystem github          # Remove servers
thv rm --all                      # Remove all

thv logs filesystem               # Container logs
thv logs filesystem --follow      # Real-time
thv logs filesystem --proxy       # Proxy logs
thv logs prune                    # Clean orphaned logs

Note: Remote servers trigger fresh OAuth authentication on start.

Registry Operations

thv registry list                    # List all servers
thv registry list --format json      # JSON output
thv search github                    # Search by keyword
thv registry info github             # Detailed server info

Custom registry:

thv config set-registry https://my-registry.example.com  # Remote
thv config set-registry /path/to/local/registry          # Local
thv config get-registry                                   # View current
thv config unset-registry                                 # Reset to default

Group Management

All servers are assigned to default group unless specified.

thv group create development           # Create group
thv group list                         # List groups
thv run fetch --group development      # Assign server to group
thv group run kubernetes               # Run all servers from registry group
thv group rm development               # Remove group (servers move to default)
thv group rm development --with-workloads  # Remove group AND its servers

Each server belongs to one group. To run same server in multiple groups, create uniquely named instances.

Secrets Management

Setup is required before use: thv secret setup (interactive provider selection).

Providers: Encrypted (AES-256-GCM, password in OS keyring) or 1Password (read-only, requires OP_SERVICE_ACCOUNT_TOKEN).

thv secret set MY_API_KEY              # Interactive input
echo "value" | thv secret set MY_KEY   # Piped input
thv secret list                        # List all
thv secret get MY_API_KEY              # Retrieve
thv secret delete MY_API_KEY           # Remove

Using secrets with servers:

thv run github --secret GITHUB_TOKEN,target=GITHUB_PERSONAL_ACCESS_TOKEN
thv run server --secret KEY1,target=ENV1 --secret KEY2,target=ENV2

Client Configuration

thv client status              # Check all supported clients
thv client setup               # Interactive setup
thv client register claude-code --group development  # Register with group
thv client list-registered     # List registered
thv client remove              # Remove client

Permissions and Network Isolation

Permission profiles control what a container can access (filesystem, network):

thv run myserver --permission-profile network          # Network access only
thv run myserver --permission-profile none             # No extra permissions
thv run myserver --permission-profile ./custom.json    # Custom profile (JSON)

Registry servers include a default profile. Without registry info, default is network.

Network isolation restricts outbound traffic to an allowlist via an egress proxy:

thv run myserver --isolate-network    # Block all outbound except allowlisted hosts

Volume mounts for filesystem access:

thv run filesystem -v /home/user/projects:/workspace:ro    # Read-only mount

.thvignore hides sensitive files from volume mounts using gitignore-style patterns. Place .thvignore in mounted directories or globally at ~/.config/toolhive/thvignore. Disable global patterns with --ignore-globally=false.

For detailed examples, see [EXAMPLES.md](references/EXAMPLES.md#permissions-and-network-isolation).

Building, Export, and Tool Overrides

thv build uvx://mcp-server-git                                      # Build container
thv build --tag my-registry/server:v1.0 npx://package               # Custom tag
thv build --dry-run --output Dockerfile.mcp uvx://mcp-server-git    # Dockerfile only

thv export my-server ./config.json              # Export JSON
thv export my-server ./server.yaml --format k8s # Export Kubernetes YAML
thv run --from-config ./config.json             # Import config

For tool overrides, see [EXAMPLES.md](references/EXAMPLES.md#tool-filtering-and-overrides).

Skills Management

Requires thv serve to be running. Skills have two scopes: user (global, default) and project (local to a project root).

thv skill install my-skill                              # Install from registry
thv skill install ghcr.io/org/skill:v1.0                # Install by OCI reference
thv skill install my-skill --clients claude-code          # Target specific client(s)
thv skill install my-skill --scope project --project-root .  # Project-scoped
thv skill install my-skill --group development           # Add to group
thv skill install my-skill --force                       # Overwrite existing

thv skill list                                           # List all installed
thv skill ls --scope user --format json                  # Filter and format
thv skill ls --client claude-code --group dev            # Filter by client/group

thv skill info my-skill                                  # Show details
thv skill info my-skill --format json                    # JSON output

thv skill uninstall my-skill                             # Remove skill
thv skill uninstall my-skill --scope project --project-root .

thv skill validate ./my-skill-dir                        # Check skill definition
thv skill build ./my-skill-dir                           # Build OCI artifact
thv skill build ./my-skill-dir --tag ghcr.io/org/skill:v1.0
thv skill push ghcr.io/org/skill:v1.0                   # Push to registry

For all flags and detailed examples, see [COMMANDS.md](references/COMMANDS.md#skill-commands) and [EXAMPLES.md](references/EXAMPLES.md#skills-management-examples).

Debugging

thv inspector filesystem                        # MCP Inspector UI
thv mcp list tools --server filesystem
thv mcp list resources --server filesystem
thv mcp list prompts --server filesystem
thv mcp call read_file --server filesystem --args '{"path":"/etc/hosts"}'  # Invoke a tool
thv runtime check                               # Verify container runtime

For tool invocation patterns (file args, stdin, JSON output, error handling), see [EXAMPLES.md](references/EXAMPLES.md#invoke-a-tool).

Guardrails

NEVER use docker rm or podman rm on ToolHive-managed containers -- always use thv rm for proper cleanup.
NEVER pass secrets as -e SECRET=value -- use --secret with managed secrets instead.
Confirm destructive operations (thv rm --all, thv stop --all, thv group rm --with-workloads) with the user before running.
Skill commands require thv serve to be running. If a skill command fails with a connection error, suggest starting thv serve first.
If the user asks about Kubernetes deployment, this skill does not cover the operator -- direct them accordingly.

Error Handling

| Symptom | Cause | Recovery | |---------|-------|----------| | Container can't reach localhost | Bridge network isolation | Use host.docker.internal (Docker Desktop), host.containers.internal (Podman), 172.17.0.1 (Linux) | | Port already in use | Another server on same port | Use --proxy-port <different-port> | | Permission denied on volume | Mount path or profile issue | Check volume mount paths and permission profiles (--permission-profile) | | Container runtime not found | No runtime or socket issue | Run thv runtime check; override socket with TOOLHIVE_PODMAN_SOCKET, TOOLHIVE_COLIMA_SOCKET, or TOOLHIVE_DOCKER_SOCKET | | Secret operation fails | Provider not configured | Run thv secret setup first | | Image pull fails | Network or auth issue | Check network connectivity; for private registries, ensure credentials are configured | | Remote auth token expired | OAuth token lifetime exceeded | Restart the server (thv restart) to trigger fresh authentication | | Sensitive files exposed in mount | No .thvignore configured | Add .thvignore in mounted directory or globally at ~/.config/toolhive/thvignore | | Skill command fails with connection error | thv serve not running | Start thv serve before using skill commands | | Skill validation fails | Invalid SKILL.md or directory structure | Run thv skill validate ./path and fix reported errors |

Global Options

--debug: Verbose output
-h, --help: Command help

Container runtime auto-detected: Podman -> Colima -> Docker.