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.

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

Replace cognee_data with either:

A named Docker volume, such as cognee_data:/app/data
A local directory path, such as ./cognee_data:/app/data

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. If you run the MCP server in a network-restricted container that does not already contain the extension, the adapter attempts a one-time runtime INSTALL JSON; LOAD JSON; on startup. When it cannot install or load the extension, it 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
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-mini}"
    volumes:
      - cognee_data:/app/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-mini}"
    depends_on:
      - cognee-backend
    networks:
      - cognee_internal

volumes:
  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) downloads a JSON extension at startup, which some graph queries (such as recall and temporal search) rely on. In a network-restricted container, that download can fail and queries surface a cryptic Extension: json ... has not been installed Binder error.The published cognee/cognee-mcp image now 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.When the extension still cannot be installed (for example, an offline container built without network access), the server now 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.

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

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