Local Setup - Cognee Documentation

Build and run Cognee MCP from source to access advanced customization, multiple transport options, and the latest development features, including the current memory-oriented MCP tools.

Advantages of Local Setup

Full Control: Customize server configuration, add providers, and modify behavior
Latest Features: Access development features before they reach Docker releases
Multiple Transports: Choose stdio, SSE, or HTTP transport modes
Current Tool Surface: Use remember, recall, and forget alongside compatibility tools
Development Ready: Debug, modify, and contribute to the codebase

Setup Steps

Clone Repository

git clone https://github.com/topoteretes/cognee.git
cd cognee

Create Environment File

Create a .env file with your configuration:

LLM_API_KEY="your-openai-api-key"

Install Dependencies

First, install the uv package manager for your operating system:

macOS / Linux
Windows
Any (pip)

# via Homebrew
brew install uv

# or via the standalone installer
curl -LsSf https://astral.sh/uv/install.sh | sh

# in PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

pip install uv

Then install the project dependencies. These commands are the same on every platform:

cd cognee-mcp
uv sync --dev --all-extras --reinstall

When to re-run uv sync. Re-run it after pulling new commits, switching branches, or updating Cognee — anytime pyproject.toml or uv.lock may have changed. For routine refreshes, use uv sync --dev --all-extras; keep --reinstall for the first install or when your environment looks stale or broken.

Activate and Run

# Run with default stdio transport
uv run cognee-mcp

Running in API Mode

To connect the MCP server to an existing Cognee backend instead of running standalone:

# Start MCP in HTTP or SSE mode pointing to the backend
uv run cognee-mcp --transport http --api-url http://localhost:8080

# Optional: add an auth token if the backend requires it
uv run cognee-mcp --transport http --api-url http://localhost:8080 --api-token your_backend_token

When --api-url is provided, the MCP server acts as an interface to the centralized backend. This allows multiple MCP instances and clients to share the same knowledge graph. You can also pass these as command-line arguments:

uv run cognee-mcp --transport http --api-url http://localhost:8080 --api-token your_token

The source-run uv run cognee-mcp entrypoint reads --api-url and --api-token flags. The API_URL and API_TOKEN environment variables are used by the Docker entrypoint wrapper, not by the source runner directly.

Use cases:

Team collaboration with shared memory
Multiple AI clients accessing consistent data
Centralized knowledge graph management

Further details

Transport Modes

Choose the transport mode based on your client requirements:

stdio (default)
HTTP
SSE

Default mode for most MCP clients. The client starts the server as a subprocess and communicates through standard input/output.

uv run cognee-mcp
# or equivalently:
uv run cognee-mcp --transport stdio

Configure your MCP client to launch the server directly:

{
  "mcpServers": {
    "cognee": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/cognee-mcp",
        "run", "cognee-mcp"
      ]
    }
  }
}

Replace /absolute/path/to/cognee-mcp with the actual path to your cloned cognee-mcp directory.

HTTP transport mode. The server starts on http://127.0.0.1:8000 and exposes a Streamable HTTP endpoint at /mcp.

uv run cognee-mcp --transport http
# Custom host/port:
uv run cognee-mcp --transport http --host 0.0.0.0 --port 9000

Configure your MCP client to connect to the HTTP endpoint:

{
  "mcpServers": {
    "cognee": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Verify the server is running with the health check endpoint:

curl http://localhost:8000/health

Server-Sent Events transport mode. The server starts on http://127.0.0.1:8000 and exposes an SSE endpoint at /sse.

uv run cognee-mcp --transport sse
# Custom host/port:
uv run cognee-mcp --transport sse --host 0.0.0.0 --port 9000

Configure your MCP client to connect to the SSE endpoint:

{
  "mcpServers": {
    "cognee": {
      "url": "http://localhost:8000/sse"
    }
  }
}

If you encounter errors on first run, reset your MCP configuration and restart.

Server Arguments Reference

All available arguments for uv run cognee-mcp:

Argument	Default	Description
`--transport`	`stdio`	Transport protocol: `stdio`, `http`, or `sse`
`--host`	`127.0.0.1`	Host to bind the server to (HTTP/SSE only)
`--port`	`8000`	Port to bind the server to (HTTP/SSE only)
`--path`	`/mcp`	URL path for the HTTP endpoint
`--log-level`	`info`	Log verbosity: `debug`, `info`, `warning`, or `error`
`--no-migration`	off	Skip database migrations on startup
`--api-url`	—	URL of a running Cognee backend (enables API mode)
`--api-token`	—	Auth token for the backend API (if required)
`--serve-url`	—	Cognee Cloud or remote instance URL used with `cognee.serve()`
`--serve-api-key`	—	API key for the `--serve-url` instance

Example with all options:

uv run cognee-mcp \
  --transport http \
  --host 0.0.0.0 \
  --port 8000 \
  --api-url http://localhost:8080 \
  --api-token your_token

Transport Security (DNS Rebinding & CORS)

The HTTP and SSE transports validate the Host and Origin headers on every request to protect against DNS rebinding attacks. By default, only loopback addresses (127.0.0.1, localhost, [::1]) are accepted. If you bind the server to 0.0.0.0 or a LAN IP — for example, to access it from another machine over SSH or a private network — you must whitelist the hosts you connect with, or requests will be rejected.

Variable	Default	Description
`MCP_ALLOWED_HOSTS`	—	Comma-separated extra `Host` header patterns to accept (e.g. `192.168.1.50:,myserver.local:`). Each entry must include the `:*` port glob. Matching `Origin` values (`http://<host>`) are added automatically.
`MCP_DISABLE_DNS_REBINDING_PROTECTION`	`false`	Set to `true` to disable all `Host`/`Origin` validation. Use only in trusted networks (LAN, Docker, VPN) where you control all clients.
`MCP_CORS_ALLOW_ORIGINS`	`http://localhost:3000`	Comma-separated origins allowed by the CORS middleware on the HTTP and SSE endpoints.

Local development (default): No configuration needed. The server binds to 127.0.0.1 and accepts requests from the loopback defaults.Remote deployment — strict (recommended): Run the MCP server on a remote box and connect from a local AI client. Whitelist the hostname your client uses to reach the MCP server, and set CORS to the browser or app origins that will call it.

# On the remote machine
export MCP_ALLOWED_HOSTS="myserver.local:*,192.168.1.50:*"
export MCP_CORS_ALLOW_ORIGINS="http://localhost:3000,https://chat.example.com"
uv run cognee-mcp --transport http --host 0.0.0.0 --port 8000

In this example, MCP_ALLOWED_HOSTS covers the MCP server hostnames clients connect to, while MCP_CORS_ALLOW_ORIGINS covers the calling page or app origins.Remote deployment — permissive: Disable protection entirely on a trusted private network. This skips both Host and Origin validation.

export MCP_DISABLE_DNS_REBINDING_PROTECTION=true
uv run cognee-mcp --transport http --host 0.0.0.0 --port 8000

Only disable DNS rebinding protection on networks you fully control. With protection off, any website your browser visits could issue requests against the MCP server.

These variables can also be set in your .env file alongside LLM_API_KEY and other configuration. They apply equally to source runs (uv run cognee-mcp) and the Docker image used in the Quickstart.

The preferred MCP workflow is to use remember, recall, and forget. The server also exposes legacy-compatible tools such as cognify and search when you need lower-level control.

Next Steps

After starting the server, configure your AI client to connect to it. See the integrations section for client-specific setup instructions.

Need Help?

Join Our Community

Get support and connect with other developers using Cognee MCP.

​Advantages of Local Setup

​Setup Steps

​Running in API Mode

​Further details

​Next Steps

​Need Help?

Join Our Community

Advantages of Local Setup

Setup Steps

Running in API Mode

Further details

Next Steps

Need Help?