Cognee MCP Quickstart - Cognee Documentation

Start the Cognee MCP server using Docker to quickly test AI memory integration.

Prerequisites

Docker installed and running
OpenAI API key

Setup Steps

Set Your API Key

export LLM_API_KEY=your_api_key_here

Create Environment File

echo "LLM_API_KEY=your_api_key_here" > .env

Start the Server

docker run -e TRANSPORT_MODE=http --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main

The server starts on port 8000 with HTTP transport mode.

Verify the Server

curl http://localhost:8000/health

You should see a healthy response from the server.

Persist Data

By default, the container removes its local data when it stops. Use a bind mount or named Docker volume if you want memory to survive restarts. The image stores everything under /cognee-storage, which is where you must mount:

ENV SYSTEM_ROOT_DIRECTORY=/cognee-storage/system
ENV DATA_ROOT_DIRECTORY=/cognee-storage/data

system holds the embedded graph and vector files; data holds ingested files and loader outputs. Mount both:

docker run -e TRANSPORT_MODE=http --env-file ./.env -p 8000:8000 \
  -v cognee_system:/cognee-storage/system \
  -v cognee_data:/cognee-storage/data \
  --rm -it cognee/cognee-mcp:main

Each source can be either:

A named Docker volume, such as cognee_data:/cognee-storage/data
A local directory path, such as ./cognee_data:/cognee-storage/data

The container runs as the non-root user cognee (uid/gid 1000). A fresh named volume picks up that ownership from the image and is writable straight away; a host directory keeps its own ownership, so run chown -R 1000:1000 ./cognee_data before mounting it, or ingestion fails with PermissionError: [Errno 13] Permission denied.The cognee/cognee backend image defaults to the same paths and the same uid, so pointing both at one pair of volumes gives the API server and the MCP server a shared memory store.

Kuzu/Ladybug JSON Extension

The default Ladybug (Kuzu) graph backend needs its JSON extension for graph queries that rely on JSON — including recall and temporal search. The cognee/cognee-mcp image pre-installs this extension at build time, so it is baked into the image even when the container has no network access at runtime. Pulling the latest image (or rebuilding it) ensures the extension is present. Starting with the next cognee release, the extension binaries also ship inside the cognee package itself and are loaded from disk before the network is ever tried, so an image built on that release carries the extension whether or not the build-time pre-install ran. The runtime INSTALL JSON; LOAD JSON; remains only as a last resort, for the platforms the bundle does not cover — see Graph Stores. When no step succeeds, the adapter logs a warning explaining that JSON-dependent queries (such as recall and temporal search) will otherwise fail with Extension: json ... has not been installed. To resolve it, give the process network access at startup, use an image that already bundles the extension, or run INSTALL json; LOAD json; once against the database.

API Mode (Shared Knowledge Graph)

To connect multiple clients to a shared knowledge graph, run MCP in API mode pointing to a centralized Cognee backend:

Start Cognee Backend

First, start a Cognee backend instance:

docker run -e LLM_API_KEY=your_api_key_here -p 8080:8000 --rm -it cognee/cognee:main

Start MCP in API Mode

Start the MCP server and point it to the backend:

docker run -e TRANSPORT_MODE=http -e API_URL=http://localhost:8080 -p 8000:8000 --rm -it cognee/cognee-mcp:main

The container rewrites localhost / 127.0.0.1 in API_URL to a host-reachable address so the MCP container can reach a backend running on your host machine. The entrypoint auto-detects the address using the following fallback order: host.docker.internal (Docker Desktop), then host.lima.internal (Colima / Lima), then the container’s default gateway IP (plain Linux Docker, typically 172.17.0.1). If none resolve it keeps host.docker.internal and prints guidance. This means Docker Desktop, Colima, and plain Linux Docker generally work without manual configuration. The MCP server now acts as an interface to the shared backend.

Connect Additional Clients (Optional)

If you need to support multiple clients, start additional MCP instances on different ports:

docker run -e TRANSPORT_MODE=http -e API_URL=http://localhost:8080 -p 8001:8000 --rm -it cognee/cognee-mcp:main

Each client connects to its own MCP instance, but all share the same knowledge graph through the backend.

The API mode requires SSE or HTTP transport
If API_URL uses localhost / 127.0.0.1, the container rewrites it to the first host address it can resolve: host.docker.internal (Docker Desktop), then host.lima.internal (Colima / Lima), then the default gateway IP (plain Linux Docker, typically 172.17.0.1)
If auto-detection still fails, use --network host (Linux) or set API_URL to a bridge address such as http://172.17.0.1:8000 directly; on Colima, start the VM with colima start --network-address
Add -e API_TOKEN=your_token if your backend requires authentication
- The container’s startup log prints calling cognee-mcp … --api-token <redacted>, so the token is not readable from docker logs (it is still visible via docker inspect and the container’s process arguments)
For backend authentication setup and how to obtain a Bearer token, see Deploy REST API Server

Docker Compose (Production Setup)

For production deployments, use Docker Compose to run the Cognee backend and MCP server together. This avoids localhost mapping issues and uses Docker’s internal DNS for service discovery.

docker-compose.yml

services:
  cognee-backend:
    image: cognee/cognee:main
    container_name: cognee-backend
    restart: unless-stopped
    ports:
      - "8080:8000"
    environment:
      LLM_API_KEY: "${LLM_API_KEY}"
      LLM_PROVIDER: "${LLM_PROVIDER:-openai}"
      LLM_MODEL: "${LLM_MODEL:-openai/gpt-5.6-luna}"
    volumes:
      # The image's baked-in SYSTEM_ROOT_DIRECTORY / DATA_ROOT_DIRECTORY
      - cognee_system:/cognee-storage/system
      - cognee_data:/cognee-storage/data
    networks:
      - cognee_internal

  cognee-mcp:
    image: cognee/cognee-mcp:main
    container_name: cognee-mcp
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      TRANSPORT_MODE: "http"
      API_URL: "http://cognee-backend:8000"
      LLM_API_KEY: "${LLM_API_KEY}"
      LLM_PROVIDER: "${LLM_PROVIDER:-openai}"
      LLM_MODEL: "${LLM_MODEL:-openai/gpt-5.6-luna}"
    depends_on:
      - cognee-backend
    networks:
      - cognee_internal

volumes:
  cognee_system:
  cognee_data:

networks:
  cognee_internal:
    driver: bridge

Networking notes:

Use the service name (cognee-backend) as the hostname in API_URL — Docker resolves it automatically within the same network.
Use the internal port (8000) in API_URL, not the host-mapped port (8080).
If you place a reverse proxy (Nginx, Caddy) in front, you do not need to set a Host: localhost header — the backend accepts requests on any host.
Add -e API_TOKEN=your_token to the MCP service if your backend requires authentication.

Troubleshooting

Graph queries fail with 'Extension: json ... has not been installed'

The default Ladybug graph store (Kuzu) needs a JSON extension for some graph queries (such as recall and temporal search). Wherever that extension has to be downloaded, a network-restricted container can fail to get it, and queries surface a cryptic Extension: json ... has not been installed Binder error.The published cognee/cognee-mcp image bakes this extension in at build time, so pulling and running the latest image is enough. If you build the MCP image yourself, rebuild it after updating to pick up this change. Starting with the next cognee release the binaries ship inside the package as well, so the download is skipped entirely on the platforms the bundle covers — see Graph Stores for the two it does not.When the extension still cannot be loaded (for example, an Alpine-based container built without network access), the server logs a clear warning at startup and attempts to install and load the extension directly on its database connection. To remediate, either give the process network access at startup, pre-install the extension in your image, or run INSTALL json; LOAD json; once against the database.

Client gets repeated 404s on /sse (or /mcp)

The TRANSPORT_MODE environment variable sets which endpoint the container exposes, and it must match the URL your MCP client connects to. A 404 on /sse almost always means the client is pointed at the SSE endpoint while the server was started with TRANSPORT_MODE=http (or vice versa).

`TRANSPORT_MODE`	Endpoint exposed	Client URL
`http` (Streamable HTTP)	`/mcp`	`http://localhost:8000/mcp`
`sse` (Server-Sent Events)	`/sse`	`http://localhost:8000/sse`
`stdio` (default)	none (subprocess over stdin/stdout)	not applicable — the client launches the process directly

stdio is the default when TRANSPORT_MODE is unset, so a network client (http/sse) needs the variable set explicitly, as in the Quickstart. To fix the 404, either change your client’s URL to match the running mode, or restart the container with the TRANSPORT_MODE your client expects:

# Client expects /sse → start the server in SSE mode
docker run -e TRANSPORT_MODE=sse --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main

The /health check answers on any of the network modes, so a healthy /health but a 404 on /sse or /mcp is a transport mismatch, not a server that failed to start. See Local Setup — Transport Modes for the full list of transports and their client configuration.

Passing --transport / --port on the docker run command line

Anything you append after the image name is forwarded to the MCP server and takes precedence over the TRANSPORT_MODE / HTTP_PORT environment defaults, because the entrypoint appends your flags last and the server keeps the last occurrence of each flag:

# Serves Streamable HTTP on port 9000 — no TRANSPORT_MODE / HTTP_PORT needed
docker run --env-file ./.env -p 9000:9000 --rm -it \
  cognee/cognee-mcp:main --transport http --port 9000

A runtime --transport also decides whether the entrypoint adds its bind defaults: with --transport http it appends --host 0.0.0.0 --port $HTTP_PORT (port 8000 unless HTTP_PORT is set) even when TRANSPORT_MODE is unset, so the server is reachable from outside the container. In the default stdio mode no bind arguments are added.In earlier images the environment defaults were appended after your flags and silently replaced them, so a command-line --transport http fell back to stdio.

The container’s HEALTHCHECK reads TRANSPORT_MODE and HTTP_PORT, not the command-line flags. With flags only, docker ps reports the container healthy without probing anything. Set the environment variables as well — -e TRANSPORT_MODE=http -e HTTP_PORT=9000 — if you rely on Docker’s health state (for example condition: service_healthy in Compose).

Why is the image so large and why does it install NVIDIA/CUDA packages?

The cognee/cognee-mcp image is several GB because it bundles Cognee’s document-processing stack. The MCP package installs cognee[postgres-binary,docs,neo4j], and the docs extra pulls unstructured[pdf] for parsing PDFs, Office files, and other documents. That chain brings in heavy ML libraries — torch, torchvision, timm, onnxruntime, and opencv-python — used by unstructured-inference for layout/OCR models.The nvidia-*-cu12 (CUDA) packages you see during the build come from the default PyPI torch wheel, which bundles the CUDA runtime as hard dependencies. They are installed regardless of whether a GPU is present, and account for most of the image size. No GPU or NVIDIA driver is required to run the server — these libraries simply ship with the standard torch wheel and fall back to CPU.There is currently no published slim / CPU-only image variant, but a CPU-only image is on the way. If you don’t need document parsing and want a smaller build today, remove the docs extra from cognee-mcp/pyproject.toml, regenerate cognee-mcp/uv.lock, and build a custom image from the source Dockerfile. The Dockerfile uses uv sync --frozen, so the lockfile must match the edited dependency set. Removing docs drops the unstructured, torch, and CUDA dependencies. See Local Setup for building from source.

Connect to AI Clients

After starting the server, connect it to your AI development tool:

Cursor

AI-powered code editor with native MCP support

Claude Code

Command-line AI assistant from Anthropic

Codex

OpenAI coding agent with built-in MCP support

Cline

VS Code extension for AI-assisted development

Continue

Open-source AI coding assistant

Python Agent

Build your own MCP client

Next Steps

Tools Reference

See all available MCP tools and operations

Local Setup

Install the PyPI release with uvx, or run from source for customization and development

​Prerequisites

​Setup Steps

​Persist Data

​Kuzu/Ladybug JSON Extension

​API Mode (Shared Knowledge Graph)

​Docker Compose (Production Setup)

​Troubleshooting

​Connect to AI Clients

Cursor

Claude Code

Codex

Cline

Continue

Python Agent

​Next Steps

Tools Reference

Local Setup

Prerequisites

Setup Steps

Persist Data

Kuzu/Ladybug JSON Extension

API Mode (Shared Knowledge Graph)

Docker Compose (Production Setup)

Troubleshooting

Connect to AI Clients

Next Steps