Claude Desktop Integration

Claude Desktop is Anthropic’s native app for macOS and Windows. It supports MCP servers through a config file that you edit manually — no command-line setup required after initial configuration.

Prerequisites

Claude Desktop installed
Cognee MCP server available (see Quickstart or Local Setup)
OpenAI API key (for standalone mode) or Cognee Cloud credentials (for Cloud-connected mode)

Config file location

Find the claude_desktop_config.json file for your platform:

Platform	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

If the file does not exist yet, create it (and any missing parent directories).

Setup Steps

Open the config file

macOS
Windows

open ~/Library/Application\ Support/Claude/

Open claude_desktop_config.json in your editor of choice.

Press Win + R, type %APPDATA%\Claude and press Enter. Open claude_desktop_config.json in Notepad or your editor.

Add the Cognee server

Choose the mode that matches your setup:

Cloud-connected
Standalone (local)
Remote / self-hosted URL

Point the MCP server at your Cognee Cloud tenant using your API Base URL and API key from the API Keys page:

{
  "mcpServers": {
    "cognee": {
      "command": "cognee-mcp",
      "args": [
        "--transport", "stdio",
        "--serve-url", "https://your-tenant.aws.cognee.ai",
        "--serve-api-key", "your-cognee-cloud-api-key"
      ]
    }
  }
}

Alternatively, set environment variables instead of inline args:

{
  "mcpServers": {
    "cognee": {
      "command": "cognee-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "COGNEE_BASE_URL": "https://your-tenant.aws.cognee.ai",
        "COGNEE_API_KEY": "your-cognee-cloud-api-key"
      }
    }
  }
}

Run the MCP server locally with its own knowledge graph. Requires an LLM API key:

{
  "mcpServers": {
    "cognee": {
      "command": "cognee-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "LLM_API_KEY": "your-openai-api-key"
      }
    }
  }
}

If you installed from source with uv, use the full uv run invocation:

{
  "mcpServers": {
    "cognee": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/cognee-mcp",
        "run", "cognee-mcp",
        "--transport", "stdio"
      ],
      "env": {
        "LLM_API_KEY": "your-openai-api-key"
      }
    }
  }
}

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

Connect to a Cognee MCP server that is already running and exposed on a public domain — for example, a self-hosted backend where you started the server with cognee-mcp --transport http --host 0.0.0.0 behind a reverse proxy. Claude Desktop only launches stdio servers directly, so use the mcp-remote bridge to reach an HTTP/SSE URL. This requires Node.js (for npx).

{
  "mcpServers": {
    "cognee": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://cognee.example.com/mcp"
      ]
    }
  }
}

Use the /mcp path for an HTTP-transport server and /sse for an SSE-transport server. If the endpoint is protected (for example, a bearer token enforced at your reverse proxy), pass it as a header:

{
  "mcpServers": {
    "cognee": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://cognee.example.com/mcp",
        "--header", "Authorization: Bearer your-token"
      ]
    }
  }
}

On the server, whitelist the public hostname with MCP_ALLOWED_HOSTS (and browser origins with MCP_CORS_ALLOW_ORIGINS), or the transport’s DNS-rebinding protection rejects the requests. See Transport Security.

Restart Claude Desktop

Fully quit and reopen Claude Desktop. On macOS, use Cmd + Q (not just closing the window) to ensure the app reloads the config.

Verify the connection

Open a new conversation in Claude Desktop and ask:

“What Cognee tools do you have available?”

Claude should list tools such as remember, recall, and forget. If the tools don’t appear, check Troubleshooting below.

Use Cognee tools

Claude Desktop will use Cognee tools automatically when relevant. You can also prompt explicitly:

“Remember this in Cognee: we use PostgreSQL for the main database”
“Recall what you know about our database choices from Cognee”

Troubleshooting

Tools don't appear after restart

Confirm the config file is valid JSON (no trailing commas, correct bracket nesting).
On macOS, make sure you fully quit the app with Cmd + Q.
Check that cognee-mcp is on your PATH: run which cognee-mcp in a terminal. If it isn’t found, use the full path in the command field.
For source installs, verify the --directory path points to the folder that contains pyproject.toml.

Authentication errors (Cloud mode)

Confirm the --serve-url (or COGNEE_BASE_URL) value matches exactly the API Base URL on your API Keys page — no trailing slash.
Regenerate your API key if it may have expired and update the config.
Verify the key value has no surrounding quotes or extra whitespace.

Can't connect to a remote MCP URL

Confirm the URL path matches the server transport: /mcp for HTTP, /sse for SSE.
Make sure npx (Node.js) is installed and on your PATH — run npx --version.
If the connection is rejected, whitelist your public hostname on the server with MCP_ALLOWED_HOSTS and set MCP_CORS_ALLOW_ORIGINS. See Transport Security.
Open the URL’s health endpoint in a browser (e.g. https://cognee.example.com/health) to confirm the server is reachable from outside your network.

Server crashes on startup

Run cognee-mcp --transport stdio directly in a terminal to see error output. Common causes are a missing LLM_API_KEY in standalone mode or an unreachable --serve-url endpoint.

Need Help?

Join Our Community

Get support and connect with other developers using Cognee MCP.

​Claude Desktop Integration

​Prerequisites

​Config file location

​Setup Steps

​Troubleshooting

​Need Help?