# 🚀 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_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:

```bash
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/`:

```bash
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:

```bash
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:

```bash
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:

```bash
# 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:

```json
{
  "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:

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

When the settings open, enhance the args as follows:

```json
{
  "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:

```json
{
  "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

1. Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/)
2. Install [Claude for Desktop](https://claude.ai/download).
3. 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.
