Neo4j Knowledge Graph MCP Server

MCP server for enterprise knowledge graph retrieval over Neo4j. Client LLM generates Cypher; this server provides schema resources, validation, and read-only execution.

中文详细说明请参阅：docs/知识图谱检索MCP服务说明.md

Architecture

• 10 Resources: 7 static (schema, constraints, conventions, semantics, glossary, patterns, safety) + 3 dynamic (stats, samples, indexes)
• 7 Tools: get_graph_context, get_cypher_prompt, validate_cypher, execute_cypher, explain_cypher, resolve_entity, refresh_graph_stats
• 4 Prompts: generate_cypher_query, refine_cypher_query, explain_query_result, decompose_complex_question

Context Tools (get_graph_context_tool, get_cypher_prompt_tool) provide the same schema context as Resources/Prompts for Tools-only MCP clients that do not support resources/read or prompts/get.

Setup

python3 -m venv .venv
source .venv/bin/activate
pip install mcp neo4j pyyaml pydantic pydantic-settings

Environment variables:

Variable	Default	Description
NEO4J_URI	bolt://localhost:7687	Neo4j Bolt URI
NEO4J_USER	neo4j	Neo4j user
NEO4J_PASSWORD	password	Neo4j password
NEO4J_DATABASE	neo4j	Neo4j database
MCP_TRANSPORT	stdio	stdio | streamable-http | sse
MCP_HOST	127.0.0.1	HTTP/SSE bind host
MCP_PORT	8000	HTTP/SSE bind port
MCP_SSE_PATH	/sse	SSE endpoint path
MCP_STREAMABLE_HTTP_PATH	/mcp	Streamable HTTP endpoint path

Copy .env.example to .env and adjust as needed.

Import graph data

From ontology_system:

curl -o graph-import.cypher http://localhost:8183/graph/export/cypher
cypher-shell -u neo4j -p password -f graph-import.cypher

Run MCP server

stdio（默认，Cursor 子进程模式）

PYTHONPATH=. python -m src.server

streamable-http（推荐 HTTP 模式）

PYTHONPATH=. python -m src.server --transport streamable-http --host 127.0.0.1 --port 8000

Endpoint: http://127.0.0.1:8000/mcp

SSE

PYTHONPATH=. python -m src.server --transport sse --host 127.0.0.1 --port 8000

Endpoint: http://127.0.0.1:8000/sse

局域网访问（Cherry Studio 等远程客户端）

绑定 0.0.0.0 时，必须配置允许的 Host 头，否则会出现 421 Misdirected Request：

PYTHONPATH=. python -m src.server \
  --transport streamable-http \
  --host 0.0.0.0 \
  --port 7688 \
  --allowed-host 192.168.0.18:7688

或使用环境变量：

export MCP_ALLOWED_HOSTS=192.168.0.18:7688
PYTHONPATH=. python -m src.server --transport streamable-http --host 0.0.0.0 --port 7688

局域网临时调试可加 --disable-transport-security（不推荐生产环境）。

绑定 0.0.0.0 前请确认网络访问控制；生产环境建议置于反向代理之后。

Cursor MCP configuration

stdio（command）

{
  "mcpServers": {
    "knowledge-graph": {
      "command": "/path/to/mcp_knowledge_graph/.venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/mcp_knowledge_graph",
      "env": {
        "PYTHONPATH": "/path/to/mcp_knowledge_graph",
        "NEO4J_URI": "bolt://192.168.0.18:7687",
        "NEO4J_PASSWORD": "password"
      }
    }
  }
}

streamable-http（url，含 Cherry Studio）

先启动服务（局域网需 --allowed-host）：

PYTHONPATH=. python -m src.server \
  --transport streamable-http \
  --host 0.0.0.0 \
  --port 7688 \
  --allowed-host 192.168.0.18:7688

Cherry Studio JSON 配置：

{
  "mcpServers": {
    "knowledge-graph": {
      "url": "http://192.168.0.18:7688/mcp"
    }
  }
}

也可通过 args 指定 transport：

{
  "mcpServers": {
    "knowledge-graph": {
      "command": "/path/to/mcp_knowledge_graph/.venv/bin/python",
      "args": ["-m", "src.server", "--transport", "streamable-http", "--port", "8000"],
      "cwd": "/path/to/mcp_knowledge_graph",
      "env": {
        "PYTHONPATH": "/path/to/mcp_knowledge_graph"
      }
    }
  }
}

Verify pipeline

PYTHONPATH=. python scripts/verify_import_pipeline.py

Tests

PYTHONPATH=. pytest tests/ -v

Workflow

Full MCP client (Resources + Prompts)

1. Client reads graph://schema, graph://ontology-constraints, graph://query-patterns
2. Optional: resolve_entity for name disambiguation
3. Client LLM uses generate_cypher_query prompt to produce Cypher JSON
4. validate_cypher → execute_cypher → explain_query_result

Tools-only client

1. get_cypher_prompt_tool(question=...) or get_graph_context_tool(scope="core")
2. Optional: resolve_entity → pass result as entity_hints
3. Platform LLM generates Cypher JSON from returned prompt fields
4. validate_cypher → execute_cypher → platform LLM explains records