taproot-mcp

Taproot

简体中文

Taproot is a local MCP server for SSH-managed nodes. The VS Code extension is the control panel for editing nodes.yaml, checking status, and preparing the shared HTTP MCP backend that your agent connects to.

Remote nodes only need SSH access. They do not need Taproot installed.

Quick Start

1. Install the VS Code extension

Install taproot-mcp from the VS Code Marketplace.

For Remote-SSH, install it under SSH: <host>, not Local.

Taproot runs on the same machine as the agent that connects to it. In a Remote-SSH VS Code window, extension commands run on the SSH host, and Codex must connect to that same host's Taproot HTTP endpoint.

CLI-only install, without VS Code:

python -m pip install https://github.com/xiaoxiao27110/taproot/releases/download/v0.2.3/taproot_mcp-0.2.3-py3-none-any.whl

2. Copy the setup prompt into your agent

Click Copy Agent Prompt in the Taproot panel or Command Palette, then paste it into your agent tool.

The prompt asks the agent to install or update taproot-mcp, start the local HTTP MCP server for the first time, and connect the agent to that server in one flow. The extension no longer runs backend installation scripts itself.

3. Add nodes

Open the Taproot panel in VS Code, add your SSH nodes, then run the connection check from the panel.

You can also check from a terminal:

taproot-mcp check --config /absolute/path/to/nodes.yaml

4. Shared HTTP backend

http://127.0.0.1:8765/mcp

Codex ~/.codex/config.toml:

[mcp_servers.taproot]
url = "http://127.0.0.1:8765/mcp"

In a Remote-SSH VS Code window, this 127.0.0.1 is the SSH host where the Taproot extension runs, not your desktop shell.

Claude Code:

claude mcp add --transport http taproot http://127.0.0.1:8765/mcp

Codex should connect to the HTTP server started from the Taproot VS Code extension. It should not launch a separate taproot-mcp subprocess.

If you need to start the server manually, the command is still available:

taproot-mcp serve --config /absolute/path/to/nodes.yaml --transport http --host 127.0.0.1 --port 8765

Other Clients

For MCP clients that launch servers by command, stdio is still available. Codex should keep using the HTTP URL above.

claude mcp add taproot -- taproot-mcp serve --config /absolute/path/to/nodes.yaml

nodes.yaml

Example:

defaults:
  user: admin
  key: ~/.ssh/id_rsa
  port: 22

nodes:
  gpu-node-1:
    host: 192.168.1.101
    tags: [gpu, vllm]
  dev-vm:
    host: 192.168.1.200
    user: dev
    tags: [dev, build]

Config lookup order:

1. TAPROOT_CONFIG
2. ./nodes.yaml
3. ~/.config/taproot/nodes.yaml

Tools

Discovery:

• cluster_nodes

Broadcast tools:

• cluster_exec
• cluster_read_file
• cluster_edit_file
• cluster_write_file
• cluster_list_dir
• cluster_glob
• cluster_system_info
• cluster_service
• cluster_upload
• cluster_download

Single-node tmux session tools:

• cluster_session_open
• cluster_session_exec
• cluster_session_read
• cluster_session_interrupt
• cluster_session_close
• cluster_session_list

Safety

• password and sudo_password in nodes.yaml are plaintext. Prefer SSH keys.
• Do not commit nodes.yaml, .taproot/, history files, approval files, SSH keys, or VSIX files.
• Taproot enforces remote permissions on the MCP server side.
• Home-internal file tools run without extra prompts, except protected directories such as ~/.ssh, ~/.gnupg, ~/.aws, ~/.kube, ~/.docker, and ~/.taproot, which are denied.
• Paths outside home, sudo=True, service mutations, tmux command execution, and clearly dangerous shell commands are executed but recorded with risk metadata in history.
• The VS Code dashboard highlights risky history entries instead of blocking for approval.
• Legacy approval files and CLI commands may still exist for compatibility, but they are not part of the normal execution path.

Development

python -m pip install -e ".[test]"
python -m pytest

VS Code extension:

cd taproot-plugin
npm install
npm test