> ## 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.
# Local Setup
> Build and run Cognee MCP from source with stdio, SSE, or HTTP transport.
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
```bash theme={null}
git clone https://github.com/topoteretes/cognee.git
cd cognee
```
Create a `.env` file with your configuration:
```bash theme={null}
LLM_API_KEY="your-openai-api-key"
```
First, install the [uv](https://docs.astral.sh/uv/getting-started/installation/) package manager for your operating system:
```bash theme={null}
# via Homebrew
brew install uv
# or via the standalone installer
curl -LsSf https://astral.sh/uv/install.sh | sh
```
```powershell theme={null}
# in PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
```bash theme={null}
pip install uv
```
Then install the project dependencies. These commands are the same on every platform:
```bash theme={null}
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.
```bash theme={null}
# 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:
```bash theme={null}
# 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:
```bash theme={null}
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
Choose the transport mode based on your client requirements:
Default mode for most MCP clients. The client starts the server as a subprocess and communicates through standard input/output.
```bash theme={null}
uv run cognee-mcp
# or equivalently:
uv run cognee-mcp --transport stdio
```
Configure your MCP client to launch the server directly:
```json theme={null}
{
"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`.
```bash theme={null}
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:
```json theme={null}
{
"mcpServers": {
"cognee": {
"url": "http://localhost:8000/mcp"
}
}
}
```
Verify the server is running with the health check endpoint:
```bash theme={null}
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`.
```bash theme={null}
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:
```json theme={null}
{
"mcpServers": {
"cognee": {
"url": "http://localhost:8000/sse"
}
}
}
```
If you encounter errors on first run, reset your MCP configuration and restart.
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:**
```bash theme={null}
uv run cognee-mcp \
--transport http \
--host 0.0.0.0 \
--port 8000 \
--api-url http://localhost:8080 \
--api-token your_token
```
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://`) 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.
```bash theme={null}
# 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.
```bash theme={null}
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](/cognee-mcp/mcp-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](/cognee-mcp/integrations) section for client-specific setup instructions.
## Need Help?
Get support and connect with other developers using Cognee MCP.