neo4j-mcp-skill
Use when installing, configuring, or troubleshooting the official Neo4j MCP server
neo4j-contrib · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add neo4j-contrib/neo4j-skills --skill neo4j-mcp-skill技能说明
name: neo4j-mcp-skill description: Use when installing, configuring, or troubleshooting the official Neo4j MCP server (neo4j/mcp) — connecting Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Kiro, or other MCP-compatible editors to a Neo4j database via stdio or HTTP transport. Covers the four MCP tools (get-schema, read-cypher, write-cypher, list-gds-procedures), read-only mode, and multi-database configuration. Does NOT cover writing Cypher queries via those tools — use neo4j-cypher-skill. Does NOT cover agent memory — use neo4j-agent-memory-skill. Does NOT cover Aura instance provisioning — use neo4j-aura-provisioning-skill. allowed-tools: Bash, WebFetch version: 1.0.2
Neo4j MCP Skill
Installs and configures the official Neo4j MCP server so AI agents can connect to Neo4j via any MCP-compatible client.
When to Use
- Connecting Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Kiro, or another editor to Neo4j via MCP
- Installing
neo4j-mcp-serverand writing the correct config for a specific editor - Switching between stdio and HTTP transport
- Enabling or disabling write access (
NEO4J_READ_ONLY) - Troubleshooting "MCP server not found" or connection errors
When NOT to Use
- Writing or optimizing Cypher queries → use
neo4j-cypher-skill - Provisioning a new Neo4j Aura instance → use
neo4j-aura-provisioning-skill - Agent long-term memory → use
neo4j-agent-memory-skill - neo4j-admin / cypher-shell / aura-cli → use
neo4j-cli-tools-skill
Available MCP Tools
| Tool | Type | What it does |
|---|---|---|
get-schema | read | Returns labels, relationship types, property keys, and indexes |
read-cypher | read | Executes read-only Cypher (MATCH, RETURN, SHOW) |
write-cypher | write | Executes write Cypher (MERGE, CREATE, SET, DELETE) — disabled when NEO4J_READ_ONLY=true |
list-gds-procedures | read | Lists available Graph Data Science procedures (requires GDS plugin) |
Installation
Step 1 — Install and find the absolute path
# Option A: pip (recommended)
pip install neo4j-mcp-server
# Option B: Download binary
# https://github.com/neo4j/mcp/releases -- macOS, Linux, Windows binaries
# Option C: Docker
docker pull neo4j/mcp
Get the absolute path — you will need this in Step 3:
which neo4j-mcp # e.g. /usr/local/bin/neo4j-mcp
# or: /Users/you/project/.venv/bin/neo4j-mcp (if installed in venv)
neo4j-mcp --version # confirm it runs
Why absolute path matters: editors (Claude Code, Cursor, Claude Desktop) spawn the MCP server as a subprocess using their own restricted PATH — not your shell's PATH. On macOS, GUI apps do not inherit
.zshrcor.zprofile. Usingneo4j-mcpas the command will silently fail; using/full/path/to/neo4j-mcpalways works. Always use the output ofwhich neo4j-mcpin thecommandfield below.
Step 2 — Prepare credentials
# .env (gitignored)
NEO4J_URI=neo4j+s://<instance>.databases.neo4j.io # Aura
# or bolt://localhost:7687 # local
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=<password>
NEO4J_DATABASE=neo4j
Verify connectivity before configuring the editor:
source .env
cypher-shell -a "$NEO4J_URI" -u "$NEO4J_USERNAME" -p "$NEO4J_PASSWORD" \
"RETURN 'connected' AS status"
# If cypher-shell not available: python3 -c "
# from neo4j import GraphDatabase, __version__
# d = GraphDatabase.driver('$NEO4J_URI', auth=('$NEO4J_USERNAME','$NEO4J_PASSWORD'))
# d.verify_connectivity(); print('connected'); d.close()"
Step 3 — Configure your editor
Pick the config block for your editor. All use STDIO transport (the MCP server runs as a subprocess of the editor).
Claude Code — add to ~/.claude/settings.json. If the file already exists, merge the neo4j block into the existing mcpServers object — do not replace the whole file.
{
"mcpServers": {
"neo4j": {
"command": "/full/path/to/neo4j-mcp",
"env": {
"NEO4J_URI": "neo4j+s://<host>",
"NEO4J_USERNAME": "neo4j",
"NEO4J_PASSWORD": "<password>",
"NEO4J_DATABASE": "neo4j",
"NEO4J_READ_ONLY": "true"
}
}
}
}
CLI alternative (sets command only — you still need to add env vars to the file):
claude mcp add neo4j /full/path/to/neo4j-mcp
Claude Desktop
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"neo4j": {
"command": "/full/path/to/neo4j-mcp",
"env": {
"NEO4J_URI": "neo4j+s://<host>",
"NEO4J_USERNAME": "neo4j",
"NEO4J_PASSWORD": "<password>",
"NEO4J_DATABASE": "neo4j",
"NEO4J_READ_ONLY": "true"
}
}
}
}
VS Code — .vscode/mcp.json (note: uses servers, not mcpServers — different from all other editors):
{
"servers": {
"neo4j": {
"type": "stdio",
"command": "/full/path/to/neo4j-mcp",
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USERNAME": "neo4j",
"NEO4J_PASSWORD": "password",
"NEO4J_DATABASE": "neo4j",
"NEO4J_READ_ONLY": "true"
}
}
}
}
Cursor — global: ~/.cursor/mcp.json / project: .cursor/mcp.json (same structure as Claude Code, uses mcpServers).
Windsurf — global: ~/.codeium/windsurf/mcp_config.json / project: .windsurf/mcp_config.json (same structure as Claude Code, uses mcpServers).
Kiro — global: ~/.kiro/settings/mcp.json / project: .kiro/settings/mcp.json. Supports ${VARIABLE} to pull from the shell environment exported before the editor launched:
{
"mcpServers": {
"neo4j": {
"command": "/full/path/to/neo4j-mcp",
"env": {
"NEO4J_URI": "${NEO4J_URI}",
"NEO4J_USERNAME": "${NEO4J_US
阅读完整来源 ↗