Skip to content

MCP Quickstart

Get started with hanzo-mcp in under 5 minutes.

Installation

# With pip
pip install hanzo-mcp[tools-all]

# With uv (recommended)
uv pip install hanzo-mcp[tools-all]

Running the Server

With Claude Code

# Run directly
uvx hanzo-mcp

# Or with Python
python -m hanzo_mcp

With Claude Desktop

Install the configuration automatically:

hanzo-mcp --install

Or manually add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "hanzo": {
      "command": "uvx",
      "args": ["hanzo-mcp"]
    }
  }
}

Restart Claude Desktop after configuration.

Basic Usage

Once running, you have access to 30+ tools:

File Operations

Read a file: read("/path/to/file.py")
Write a file: write("/path/to/file.py", "content")
Edit a file: edit("/path/to/file.py", "old", "new")

Command Execution

Run command: cmd("ls -la")
Run parallel: cmd(["npm install", "cargo build"], parallel=True)

Search files: search("pattern", path="./src")
Find files: find("*.py", path=".")
AST search: ast("def test_", path="./tests")

Memory

Store memory: create_memories(["User prefers dark mode"])
Recall: recall_memories(["user preferences"])

Transport Modes

stdio (default)

Used by Claude Code and Claude Desktop:

hanzo-mcp --transport stdio

SSE (Server-Sent Events)

For web clients and debugging:

hanzo-mcp --transport sse --port 8888

Access at http://localhost:8888

Environment Variables

Variable Description
HANZO_AUTO_BACKGROUND_TIMEOUT Auto-background timeout (default: 30s, 0 to disable)
HANZO_DEFAULT_SHELL Default shell (default: zsh)
OPENAI_API_KEY For LLM tools
ANTHROPIC_API_KEY For LLM tools

Next Steps