HCL-Lab MCP Server

h3c-hcl-mcp is an open-source MCP (Model Context Protocol) Server that enables AI agents — including Claude Desktop, Claude Code, Cursor, ChatGPT MCP Client, Cline, Roo Code, and other MCP-compatible clients — to interact with local H3C Cloud Lab (HCL) network simulation environments.

⚠️ Important: This project is a community interoperability tool. It is not affiliated with, endorsed by, or sponsored by H3C. You must legally install HCL yourself; this repository does not contain, distribute, or download any HCL executables, images, or documentation.

What It Does

• Discover HCL projects, devices, and links on your local machine
• Connect to running H3C/Comware devices through HCL loopback Telnet console or SSH
• Execute controlled Comware CLI commands (display, diagnostics)
• Retrieve device facts, interfaces, configurations, and topology data
• Analyze lab topologies and assist with network experiments
• (Future) Provision configuration changes with plan → diff → approval → apply workflow

Quick Start

Prerequisites

• Windows with H3C Cloud Lab 5.10.x installed
• Python 3.12+
• uv (recommended) or pip

Installation

# Via uvx (recommended — no explicit install needed)
uvx h3c-hcl-mcp

# Or via pip
pip install h3c-hcl-mcp
h3c-hcl-mcp

MCP Client Configuration

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "h3c-hcl": {
      "command": "uvx",
      "args": [
        "--from", "h3c-hcl-mcp==0.1.0",
        "h3c-hcl-mcp",
        "--config", "C:\\Users\\YOUR_NAME\\.config\\h3c-hcl-mcp\\config.yaml"
      ]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "h3c-hcl": {
      "command": "uvx",
      "args": [
        "--from", "h3c-hcl-mcp==0.1.0",
        "h3c-hcl-mcp",
        "--config", "C:\\Users\\YOUR_NAME\\.config\\h3c-hcl-mcp\\config.yaml"
      ]
    }
  }
}

Current Status

Version	Stage	Description
v0.0.1	Bootstrap	Repository governance, package skeleton, CI, ADR
v0.1.0	Planned	Read-only MVP — HCL project discovery, console Telnet, device facts
v1.0.0	Target	Stable API, full test coverage, multi-client verified

Current version: v0.0.1 (pre-alpha) — development has just started. See docs/design.md for the full architecture.

Architecture

Any MCP Client (Claude, Cursor, ChatGPT, …)
        │
   MCP Protocol (stdio / Streamable HTTP)
        │
   HCL-Lab MCP Server
        │
   ┌────┴────┐
   │         │
HCL Layer  Comware Layer
   │         │
Topology   CLI over
Discovery  Telnet/SSH

The codebase follows Hexagonal Architecture with strict dependency direction:

mcp → application → ports ← adapters/infrastructure
                    domain

See docs/design.md for module boundaries, port interfaces, and tool schemas.

MCP Tools (v0.1)

Tool	Status	Description
server_health	✅ Ready	Server version, config status, health checks
hcl_list_projects	✅ Ready	List local HCL projects
hcl_get_topology	✅ Ready	Devices, interfaces, links
hcl_get_runtime	✅ Ready	HCL process status, device runtime, console availability
h3c_list_devices	✅ Ready	Operable devices with transport capabilities
h3c_get_facts	✅ Ready	sysname, Comware version, uptime, model
h3c_run_display	✅ Ready	Execute whitelisted display commands
h3c_get_config	✅ Ready	Running/startup/snapshot config (redacted)
h3c_get_interfaces	Interface status, speed, description, addresses
h3c_ping	Network reachability test
h3c_trace_route	Path tracing
h3c_diff_config	Config diff without writing to device

Security

• Default: read-only. Write operations require explicit opt-in, plan approval, and audit.
• All device output is treated as untrusted data.
• Passwords are never logged or stored in plaintext.
• Commands go through whitelist validation — no shell injection, no eval.
• Only connects to 127.0.0.1 for HCL console; no LAN scanning.

See SECURITY.md for the full security model.

Development

# Clone
git clone https://github.com/FlySun1116/HCL-Lab_mcp.git
cd HCL-Lab_mcp

# Create venv and install dev dependencies
uv sync --extra dev

# Lint & typecheck
uv run ruff check .
uv run ruff format --check .
uv run mypy src/

# Run tests
uv run pytest

# Build
uv build

# Run MCP Inspector
npx @modelcontextprotocol/inspector uv run h3c-hcl-mcp

See CONTRIBUTING.md for guidelines.

License

Apache-2.0. See LICENSE and NOTICE for details.

Disclaimer

This is a community interoperability project. H3C, HCL, Comware, and related trademarks are the property of their respective owners. Users must comply with HCL's license terms and install HCL legally. This repository does not include, redistribute, or reverse-engineer any HCL proprietary software.