🚀 Memgraph MCP Server

Memgraph MCP Server is a lightweight server implementation of the Model Context Protocol (MCP) designed to connect Memgraph with LLMs and different clients.

🔧Tools

The Memgraph MCP Server exposes the following tools over MCP. Each tool runs a Memgraph‐toolbox operation and returns a list of records (dictionaries).

run_query(query: str)

Run any arbitrary Cypher query against the connected Memgraph database.

Read-Only Mode: By default, the server runs in read-only mode to prevent accidental data modifications. Write operations (CREATE, MERGE, DELETE, SET, DROP, REMOVE) are automatically blocked and will return an error. Set MCP_READ_ONLY=false to enable write operations.

Parameters:

query: A valid Cypher query string.

get_configuration()

Fetch the current Memgraph configuration settings. Equivalent to running SHOW CONFIGURATION.

get_index()

Retrieve information about existing indexes. Equivalent to running SHOW INDEX INFO.

get_constraint()

Retrieve information about existing constraints. Equivalent to running SHOW CONSTRAINT INFO.

get_schema()

Fetch the graph schema (labels, relationships, property keys). Equivalent to running SHOW SCHEMA INFO.

get_storage()

Retrieve storage usage metrics for nodes, relationships, and properties. Equivalent to running SHOW STORAGE INFO.

get_triggers()

List all database triggers. Equivalent to running SHOW TRIGGERS.

get_procedures()

List all available Memgraph procedures (query modules). Returns information about all available procedures including MAGE algorithms and custom query modules. Each procedure includes its name, signature, and whether it performs write operations. Use this to discover available graph algorithms and utility functions before executing them. Equivalent to running CALL mg.procedures() YIELD *.

get_betweenness_centrality()

Compute betweenness centrality on the entire graph. Uses BetweennessCentralityTool under the hood.

get_page_rank()

Compute PageRank scores for all nodes. Uses PageRankTool under the hood.

get_node_neighborhood(node_id: str, max_distance: int = 1, limit: int = 100)

Find nodes within a specified distance from a given node. Parameters:

node_id: The ID of the starting node to find neighborhood around
max_distance: Maximum distance (hops) to search from the starting node. Default is 1
limit: Maximum number of nodes to return. Default is 100

Uses NodeNeighborhoodTool under the hood.

search_node_vectors(index_name: str, query_vector: List[float], limit: int = 10)

Perform vector similarity search on nodes in Memgraph using cosine similarity. Parameters:

index_name: Name of the index to use for the vector search
query_vector: Query vector to search for similarity
limit: Number of similar nodes to return. Default is 10

Uses NodeVectorSearchTool under the hood.

🐳 Run Memgraph MCP server with Docker

Building Memgraph MCP image

To build the Docker image using your local memgraph-toolbox code, run from the root of the monorepo:

cd /path/to/ai-toolkit
docker build -f integrations/mcp-memgraph/Dockerfile -t mcp-memgraph:latest .

This will include your local memgraph-toolbox and install it inside the image.

Running the Docker image

1. Streamable HTTP mode (recommended for most users)

To connect to local Memgraph containers, by default the MCP server will be available at http://localhost:8000/mcp/:

docker run --rm mcp-memgraph:latest

2. Stdio mode (for integration with MCP stdio clients)

Configure your MCP host to run the docker command and utilize stdio:

docker run --rm -i -e MCP_TRANSPORT=stdio mcp-memgraph:latest

📄 Note: By default, the server will connect to a Memgraph instance running on localhost docker network bolt://host.docker.internal:7687. If you have a Memgraph instance running on a different host or port, you can specify it using environment variables.

3. Custom Memgraph connection (external instance, no host network)

To avoid using host networking, or to connect to an external Memgraph instance:

docker run --rm \
  -p 8000:8000 \
  -e MEMGRAPH_URL=bolt://memgraph:7687 \
  -e MEMGRAPH_USER=myuser \
  -e MEMGRAPH_PASSWORD=password \
  mcp-memgraph:latest

⚙️ Configuration

Environment Variables

The following environment variables can be used to configure the Memgraph MCP Server, whether running with Docker or directly (e.g., with uv or python).

Memgraph Connection

MEMGRAPH_URL: The Bolt URL of the Memgraph instance to connect to. Default: bolt://host.docker.internal:7687
- The default value allows you to connect to a Memgraph instance running on your host machine from within the Docker container.
MEMGRAPH_USER: The username for authentication. Default: memgraph
MEMGRAPH_PASSWORD: The password for authentication. Default: empty
MEMGRAPH_DATABASE: The database name to connect to. Default: memgraph

Server Configuration

MCP_SERVER: The server implementation to use. Options: server (default), memgraph-experimental
- server: Production-ready server with all stable Memgraph tools
- memgraph-experimental: Experimental server with adaptive query optimization and autonomous index management
  - Note: Read-only mode is not supported on this server as it requires write access to create indexes
MCP_TRANSPORT: The transport protocol to use. Options: streamable-http (default), stdio
MCP_READ_ONLY: Enable read-only mode to prevent write operations (CREATE, MERGE, DELETE, SET, DROP, REMOVE). Options: true (default), false
- When set to true, all write queries will be blocked with an error message
- Set to false to allow write operations on the database
- Only applies to the default server - the memgraph-experimental server ignores this setting

You can set these environment variables in your shell, in your Docker run command, or in your deployment environment.

Multi-Server Architecture

The MCP server supports multiple server implementations that can be selected via the MCP_SERVER environment variable:

server (default): Production server with all stable tools (run_query, get_schema, get_configuration, etc.)
memgraph-experimental: Experimental server with autonomous GraphRAG capabilities using FastMCP's native sampling and elicitation:

To use the experimental Memgraph server:

# With uv
MCP_SERVER=memgraph-experimental uv run mcp-memgraph
 
# With Docker
docker run --rm -e MCP_SERVER=memgraph-experimental mcp-memgraph:latest

To add a new server implementation, create a new file in src/mcp_memgraph/servers/ and register it in the AVAILABLE_SERVERS dictionary in src/mcp_memgraph/servers/__init__.py.

Connecting from VS Code (HTTP server)

If you are using VS Code MCP extension or similar, your configuration for an HTTP server would look like:

{
  "servers": {
    "mcp-memgraph-http": {
      "url": "http://localhost:8000/mcp/"
    }
  }
}

Note: The URL must end with /mcp/.

Running the Docker image in Visual Studio Code using stdio

You can also run the server using stdio for integration with MCP stdio clients:

Open Visual Studio Code, open Command Palette (Ctrl+Shift+P or Cmd+Shift+P on Mac), and select MCP: Add server....
Choose Command (stdio)
Enter docker as the command to run.
For Server ID enter mcp-memgraph.
Choose "User" (adds to user-space settings.json) or "Workspace" (adds to .vscode/mcp.json).

When the settings open, enhance the args as follows:

{
  "servers": {
    "mcp-memgraph": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MCP_TRANSPORT=stdio",
        "mcp-memgraph:latest"
      ]
    }
  }
}

To connect to a remote Memgraph instance with authentication, add environment variables to the args list:

{
  "servers": {
    "mcp-memgraph": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MCP_TRANSPORT=stdio",
        "-e",
        "MEMGRAPH_URL=bolt://memgraph:7687",
        "-e",
        "MEMGRAPH_USER=myuser",
        "-e",
        "MEMGRAPH_PASSWORD=mypassword",
        "mcp-memgraph:latest"
      ]
    }
  }
}

Open GitHub Copilot in Agent mode and you'll be able to interact with the Memgraph MCP server.

Run Memgraph MCP server with Claude

Install uv
Install Claude for Desktop.
Add the Memgraph server to Claude config

You can do it in the UI, by opening your Claude desktop app navigate to Settings, under the Developer section, click on Edit Config and add the following content:

{
    "mcpServers": {
      "mpc-memgraph": {
        "command": "uv",
        "args": [
            "run",
            "--with",
            "mcp-memgraph",
            "--python",
            "3.13",
            "mcp-memgraph"
        ]
     }
   }
}

Or you can open the config file in your favorite text editor. The location of the config file depends on your operating system:

MacOS/Linux

~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows

%APPDATA%/Claude/claude_desktop_config.json

[!NOTE] You may need to put the full path to the uv executable in the command field. You can get this by running which uv on MacOS/Linux or where uv on Windows. Make sure you pass in the absolute path to your server.

Running Memgraph

For the examples above it is assumed that you have a Memgraph running:

Run Memgraph MAGE:

docker run -p 7687:7687 memgraph/memgraph-mage --schema-info-enabled=True

The --schema-info-enabled configuration setting is set to True to allow LLM to run SHOW SCHEMA INFO query.

memgraph/mcp-memgraph