> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Start the Cognee MCP server with Docker and test it from any MCP client.

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

## Prerequisites

* Docker installed and running
* OpenAI API key

## Setup Steps

<Steps>
  <Step title="Set Your API Key">
    ```bash theme={null}
    export LLM_API_KEY=your_api_key_here
    ```
  </Step>

  <Step title="Create Environment File">
    ```bash theme={null}
    echo "LLM_API_KEY=your_api_key_here" > .env
    ```
  </Step>

  <Step title="Start the Server">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Verify the Server">
    ```bash theme={null}
    curl http://localhost:8000/health
    ```

    You should see a healthy response from the server.
  </Step>
</Steps>

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

```dockerfile theme={null}
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:

```bash theme={null}
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`

<Note>
  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.
</Note>

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

<Steps>
  <Step title="Start Cognee Backend">
    First, start a Cognee backend instance:

    ```bash theme={null}
    docker run -e LLM_API_KEY=your_api_key_here -p 8080:8000 --rm -it cognee/cognee:main
    ```
  </Step>

  <Step title="Start MCP in API Mode">
    Start the MCP server and point it to the backend:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Connect Additional Clients (Optional)">
    If you need to support multiple clients, start additional MCP instances on different ports:

    ```bash theme={null}
    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.
  </Step>
</Steps>

<Note>
  * 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](/guides/deploy-rest-api-server#authentication)
</Note>

## 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.

```yaml docker-compose.yml theme={null}
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:
      # 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-mini}"
    depends_on:
      - cognee-backend
    networks:
      - cognee_internal

volumes:
  cognee_system:
  cognee_data:

networks:
  cognee_internal:
    driver: bridge
```

<Info>
  **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.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    # 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](/cognee-mcp/mcp-local-setup) for the full list of transports and their client configuration.
  </Accordion>

  <Accordion title="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](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/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](/cognee-mcp/mcp-local-setup) for building from source.
  </Accordion>
</AccordionGroup>

## Connect to AI Clients

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

<CardGroup cols={3}>
  <Card title="Cursor" href="/cognee-mcp/integrations/cursor" icon="code">
    AI-powered code editor with native MCP support
  </Card>

  <Card title="Claude Code" href="/cognee-mcp/integrations/claude-code" icon="bot">
    Command-line AI assistant from Anthropic
  </Card>

  <Card title="Codex" href="/cognee-mcp/integrations/codex" icon="terminal">
    OpenAI coding agent with built-in MCP support
  </Card>
</CardGroup>

<CardGroup cols={3}>
  <Card title="Cline" href="/cognee-mcp/integrations/cline" icon="terminal">
    VS Code extension for AI-assisted development
  </Card>

  <Card title="Continue" href="/cognee-mcp/integrations/continue" icon="play">
    Open-source AI coding assistant
  </Card>

  <Card title="Python Agent" href="/cognee-mcp/integrations/python-agent" icon="python">
    Build your own MCP client
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Tools Reference" href="/cognee-mcp/mcp-tools" icon="wrench">
    See all available MCP tools and operations
  </Card>

  <Card title="Local Setup" href="/cognee-mcp/mcp-local-setup" icon="code">
    Run from source for customization and development
  </Card>
</CardGroup>