Memgraph MCP server

The Memgraph MCP Server is a lightweight server implementation of the Model Context Protocol (MCP) that connects Memgraph with LLMs. An MCP client, such as Claude, talks to the server over MCP, and the server runs queries in Memgraph:

Run Memgraph MCP server

To run the server with Claude Desktop:

1. Install uv.
2. Install Claude Desktop.
3. Add the Memgraph server to the Claude Desktop configuration.

The location of the configuration file depends on your operating system:

macOS

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

Windows

$env:AppData\Claude\claude_desktop_config.json

Add the server to it:

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

Chat with the database

1. Start Memgraph with MAGE:

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

   --schema-info-enabled=true lets the LLM run the SHOW SCHEMA INFO query.

2. Open Claude Desktop. The Memgraph tools and resources are listed. To try them on sample data, load a dataset from Memgraph Lab datasets.

Run Memgraph MCP server with Docker

docker pull memgraph/mcp-memgraph:latest

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

docker run --rm -p 8000:8000 memgraph/mcp-memgraph:latest

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

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

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

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

{
  "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",
        "memgraph/mcp-memgraph:latest"
      ]
    }
  }
}

Multi-tenant authentication (OIDC / JWT)

The MCP server can optionally enforce OIDC / JWT authentication on the streamable-HTTP transport and route each authenticated session to a different Memgraph logical database based on JWT claims. This is disabled by default — when off, the server behaves exactly as documented in the sections above.

Enable it when you want to:

• Serve different users different Memgraph databases on the same MCP deployment.
• Place MCP behind an OIDC provider (Keycloak, Auth0, Okta, Entra ID, …).
• Capture per-user audit trails on tool calls.

Auth-only tools

When MCP_AUTH_ENABLED=true, the server exposes two additional tools:

Environment variables

All of these are no-ops when MCP_AUTH_ENABLED=false (the default). When auth is enabled, the server fails fast at startup if any of the three required variables are missing.

How it works

1. Every request to /mcp must carry Authorization: Bearer <JWT>.
2. The middleware validates the JWT signature against the IdP’s JWKS (cached in-process and auto-refreshed when an unknown kid arrives).
3. It verifies iss, aud, exp, and the required scope.
4. It reads the tenants array claim, intersects it with MCP_TENANT_CATALOG, and builds a per-session SessionAuth keyed by Mcp-Session-Id.
5. The session’s current_tenant defaults to the JWT’s default_tenant claim (when present and allowed), otherwise the first allowed tenant.
6. Each tool call routes to the Memgraph database with the same name as current_tenant.

Within a session, users can switch among their allowed databases with the use_database tool, and discover them with list_databases.

Discovery endpoints exposed when auth is enabled

The discovery document fetched from the upstream IdP is cached in-process and re-fetched on the next request if the cache is empty (e.g., the IdP was down on the first attempt).

DCR intercept (workaround for Claude Code)

Some MCP clients — notably current Claude Code (see anthropics/claude-code#26675) — force Dynamic Client Registration even when a pre-registered clientId is configured. Setting MCP_AUTH_STATIC_CLIENT_ID=<your-public-client-id> makes the MCP server return the same pre-registered client ID for every DCR request, sidestepping the bug.

When that variable is set, the PRM document also advertises the MCP server itself as the authorization_server so DCR requests come back to the MCP server instead of going directly to the IdP. All other OAuth flows (authorize, token, JWKS) still happen against the real IdP.

What you need on the IdP side

In any OIDC provider, roughly:

1. A public client with PKCE enabled, with redirect URI patterns matching the IDEs you’ll use (e.g., http://localhost:*, vscode://*, cursor://*, claude://*).
2. A tenants claim mapper that emits a JSON-array claim of the user’s tenant memberships (in Keycloak: a Group Membership mapper; in Auth0/Okta: a custom rule reading group or role attributes).
3. An audience claim mapper baking your MCP_AUTH_AUDIENCE value into issued tokens.
4. A scope (default: mcp:tools) attached to the client.
5. For each tenant in MCP_TENANT_CATALOG, a corresponding Memgraph logical database created via CREATE DATABASE <name>.

Run Memgraph MCP server on Kubernetes

A dedicated memgraph-mcp Helm chart deploys the MCP server on Kubernetes alongside an existing Memgraph backend. See the Memgraph MCP Helm chart section for installation steps and configuration options.

Resources

• Introducing the Memgraph MCP Server: A blog post on running the Memgraph MCP server.

MCP server in Lab

Memgraph Lab is an MCP client: GraphChat can connect to MCP servers, including the Memgraph MCP server and servers you build with the Memgraph AI Toolkit:

To connect MCP servers in Memgraph Lab, see GraphChat MCP servers.

MCP server for docs

To let your AI assistant search the Memgraph documentation instead of your database, connect the Docs MCP server.