Hanzo MCP server

The Hanzo MCP Server is a unified Model Context Protocol server that provides a comprehensive set of AI development tools and UI component management capabilities. It offers modular functionality through various tool categories for file operations, UI management, automated GUI control, and AI orchestration.

Installation

Install the MCP server globally using npm:

npm install -g @hanzo/mcp

Quick Start

Start the MCP server with all tools enabled:

hanzo-mcp serve

If you only need core functionality:

hanzo-mcp serve --core-only

Disable specific tool categories as needed:

# Exclude UI tools
hanzo-mcp serve --disable-ui

# Exclude AutoGUI tools
hanzo-mcp serve --disable-autogui

# Exclude orchestration tools
hanzo-mcp serve --disable-orchestration

To view all available tools:

hanzo-mcp list-tools

For Claude Desktop integration:

hanzo-mcp install-desktop

Available Features

Core Tools

The core toolset includes 19 essential tools:

• File operations (read, write, list, create, delete, move)
• Search functionality (grep, find files, unified search)
• Editing capabilities (single and multi-edit operations)
• Shell access (command execution, background processes)

UI Tools

Enable UI component management with 11 specialized tools:

• Component listing, searching, and detail retrieval
• Source code and demo access
• Project initialization with Hanzo UI
• UI blocks and patterns
• Installation documentation

AutoGUI Tools

Automate GUI interactions with 18 tools:

• Mouse control (move, click, drag, scroll)
• Keyboard control (typing, key presses, hotkeys)
• Screen capture and pixel detection
• Image recognition with confidence matching
• Window management
• Multi-monitor support

Orchestration Tools

Coordinate AI agents with 6 advanced tools:

• Agent spawning with model-specific constraints
• Swarm orchestration (parallel or sequential)
• Critic agents for code review
• Distributed compute connections
• LLM routing with fallback chains
• Multi-agent consensus mechanisms

Advanced Usage

CLI Options

Customize your MCP server configuration:

# Enable specific categories
hanzo-mcp serve --enable-categories files,ui

# Disable specific tools
hanzo-mcp serve --disable-tools bash,shell

# List tools by category
hanzo-mcp list-tools --category ui

Programmatic Integration

Use the MCP server in your TypeScript/JavaScript applications:

import { createMCPServer } from '@hanzo/mcp';

// Basic server with core tools
const server = await createMCPServer();

// Server with UI tools enabled
const serverWithUI = await createMCPServer({
  toolConfig: {
    enableCore: true,
    enableUI: true
  }
});

// Custom configuration
const customServer = await createMCPServer({
  name: 'my-mcp-server',
  version: '1.0.0',
  toolConfig: {
    enableCore: true,
    enableUI: true,
    enableAutoGUI: true,
    enableOrchestration: true,
    disabledTools: ['bash'],
    customTools: [/* your tools */]
  }
});

AI Client Configuration

Claude Desktop

Add the following to your .mcp.json file:

{
  "mcpServers": {
    "hanzo": {
      "command": "npx",
      "args": ["@hanzo/mcp", "serve"]
    }
  }
}

Cursor

Configure Cursor by adding to .cursor/mcp.json:

{
  "mcpServers": {
    "hanzo": {
      "command": "npx",
      "args": ["@hanzo/mcp", "serve"]
    }
  }
}

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "hanzo" '{"command":"uvx","args":["hanzo-mcp"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect