HugeGraph-MCP

hugegraph-mcp exposes HugeGraph tools to AI clients through the Model Context Protocol (MCP). It supports schema inspection, structured graph queries, controlled writes, and optional natural-language query generation and graph extraction. The MCP client starts a local process and communicates over STDIO. This process is not HugeGraph Server and does not expose an HTTP MCP endpoint.

Ordinary graph queries connect directly to HugeGraph Server. Query generation, extraction, and embedding refresh also require HugeGraph-LLM, where model credentials are configured.

Requirements

• Python 3.10 or later. A separate HugeGraph-LLM service must also meet that module’s Python requirements.
• uv and an MCP client that supports STDIO.
• HugeGraph Server 1.7.0 or later, reachable from the MCP process. The default graph path is DEFAULT/hugegraph and uses the graphspace API.
• An existing graph and an account with the required permissions. See authentication and authorization.

Installation and Connection

These examples pin the published hugegraph-mcp==1.7.1 package. Cloning the repository is not required. Replace the address, graph path, and credentials with your deployment values. Verify the connection in read-only mode before enabling supported writes.

For clients that accept a mcpServers JSON configuration, add:

 1{
 2  "mcpServers": {
 3    "hugegraph": {
 4      "command": "uvx",
 5      "args": ["hugegraph-mcp@1.7.1"],
 6      "env": {
 7        "HUGEGRAPH_URL": "http://127.0.0.1:8080",
 8        "HUGEGRAPH_GRAPH_PATH": "DEFAULT/hugegraph",
 9        "HUGEGRAPH_USER": "your-user",
10        "HUGEGRAPH_PASSWORD": "your-password",
11        "HUGEGRAPH_MCP_READONLY": "true"
12      }
13    }
14  }
15}

Configuration locations and formats vary between clients. Use your client’s instructions to set the same command, arguments, and environment variables. If the client cannot find uvx, use its absolute path for command. Restart the MCP process after changing the configuration.

You can also start it in a terminal with the environment variables above already configured:

1uvx hugegraph-mcp@1.7.1

The process waits for protocol messages from the MCP client on stdin; it does not open a web page. stdout carries MCP JSON-RPC. Do not write extra shell output to that channel.

Verify the Connection

List tools through the client, then call inspect_graph_tool. The following JSON is the parameter body for MCP tools/call, not a request to send directly to the HugeGraph REST API.

1{
2  "name": "inspect_graph_tool",
3  "arguments": {"include_raw_schema": true}
4}

Check for ok=true and data.hugegraph_server_status="available". Choose an existing vertex label from the schema and replace person below with that label:

1{
2  "name": "query_graph_data_tool",
3  "arguments": {
4    "target": "vertex",
5    "operation": "page",
6    "label": "person",
7    "limit": 5
8  }
9}

This tool belongs to the default set of 16 tools. To paginate, pass the returned next_page as page on the next call, keeping the same query conditions. An empty result does not necessarily mean the connection failed; check the graph path, label, and existing data.

Toolsets and Versions

A toolset selects a group of tools within the same package. It is not a package version, HugeGraph Server version, or MCP protocol version. Version 1.7.1 accepts the following configuration names:

Any other value, including v2, core, legacy or an empty string, falls back to the 10-tool v1 set in 1.7.1 and logs an error. Both toolsets report mcp_tool_contract_version="2.0". This field describes the tool contract, not the package version.

Toolset Naming Evolution

In upcoming releases, the default toolset is renamed to core and the compatibility toolset to legacy. For the current 1.7.1 release package, continue using the configurations documented above.

• v2_core maps to core, and v1 maps to legacy. Legacy identifiers are retained as backward-compatible aliases with migration warnings.
• Inspection endpoints report core or legacy. Clients checking data.toolset or meta.toolset should update their checks accordingly.
• An unset variable defaults to core. Empty or unrecognized values halt startup rather than silently falling back.
• Toolset selection is resolved at launch; modifying configuration requires restarting the client. Compatibility mode does not bypass security or read-only controls.

Tool Capabilities

A registered tool does not imply that every operation is enabled. The current capability boundaries are summarized below. Use the tool schema returned to your client for exact parameters.

The compatibility toolset excludes inspect_schema_tool, query_graph_data_tool, mutate_graph_properties_tool, and the three write-plan tools. Switching to compatibility mode does not enable raw Gremlin execution.

Controlled Writes

To use writes, set HUGEGRAPH_MCP_READONLY=false and use a HugeGraph account with the appropriate permissions. For a confirmable operation, first run a dry-run, review its exact targets, changes, and warnings, then confirm the returned plan_id:

1{
2  "name": "confirm_write_tool",
3  "arguments": {"plan_id": "<PLAN_ID>"}
4}

Use get_write_status_tool(plan_id) to inspect the persisted result. APPLIED means all operations are confirmed successful. PARTIAL or UNKNOWN means the workflow is incomplete or its outcome is uncertain. Inspect and reconcile status before retrying; do not blindly create a replacement plan. Confirming the same completed plan again returns its recorded result without repeating the write.

The built-in SQLite state store requires a single writable MCP instance and a persistent state directory. When multiple clients start separate processes, keep them read-only initially; multi-instance writes require a shared transactional store design. Operations returning confirmable=false cannot be forced through by disabling read-only mode or enabling admin mode.

Configuration

The following defaults apply to published version 1.7.1. HugeGraph credentials and the HugeGraph-LLM API token are separate credentials.

Optional AI Features

Configure and start the model service using the HugeGraph-LLM guide, then add these entries to the MCP client’s env:

1{
2  "HUGEGRAPH_MCP_ALLOW_AI": "true",
3  "HUGEGRAPH_AI_URL": "http://127.0.0.1:8001",
4  "HUGEGRAPH_AI_TOKEN": "your-ai-service-token"
5}

Merge these entries into the earlier env object. Generation and extraction can remain read-only. Embedding refresh additionally requires:

• Client settings: HUGEGRAPH_MCP_READONLY=false, HUGEGRAPH_MCP_ADMIN_MODE=true, and confirm=true in the tool call.
• Service settings (HugeGraph-LLM): ENABLE_LOGIN=true, HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true, a strong non-default USER_TOKEN (avoiding the well-known default 4321), and valid authentication passed via MCP’s HUGEGRAPH_AI_TOKEN. Without these service-side gates, refresh requests are rejected with FEATURE_DISABLED (“Legacy Thin API writes are disabled”).

MCP and HugeGraph-LLM must connect to the same underlying HugeGraph instance. The capability check protocol only verifies graph_name and graphspace, while the actual embedding refresh executes entirely using the AI service’s independent GRAPH_URL. Modifying MCP’s HUGEGRAPH_URL does not redirect the AI service’s data target. If MCP runs on the host and AI runs in a container, they may need different addresses to reach HugeGraph: configure GRAPH_URL on the AI service to an address reachable from its container, such as http://server:8080, and ensure GRAPH_NAME and GRAPH_SPACE match MCP. Do not use the container’s 127.0.0.1 to reach the host graph service.

Capability check protocol: The updated protocol requires GET /vid-embeddings/refresh-capabilities to return protocol_version=1, transmitting the target graph and graphspace for server-side validation before refreshing embeddings. Services without this endpoint will reject refresh requests. This validation protects multi-tenant boundary integrity in future releases.

Troubleshooting

• No tools after client startup: check the uvx path, Python version, and process stderr. Waiting for protocol input in a terminal is normal.
• Structured query tool missing: check whether the compatibility toolset was selected. For 1.7.1, use v2_core or leave the variable unset.
• FEATURE_DISABLED response: check the capability table and read-only, AI, and admin settings. Some operations are disabled because of backend capability limits and cannot be enabled through configuration alone.
• AI calls fail: check the service address, token, container networking, and AI logs. An unavailable-service error does not necessarily mean a model was retired.
• Embedding calls return 400 or 429: check the provider’s input-count and request-rate limits. Batch size and concurrent request count are different limits; handle them in HugeGraph-LLM’s embedding and index-building paths, not by changing MCP toolsets.

An ok=false tool response indicates failure. Inspect error.type, error.retryable, and warnings; an established MCP connection or successful HTTP status alone does not prove that a business operation succeeded.

Next Steps

• HugeGraph-LLM
• HugeGraph-MCP source and README
• Integration checks
• PyPI package

Documentation on the repository’s main branch follows source changes. Check version applicability when using a pinned package; the installation examples on this page use 1.7.1.