> ## 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.
# Claude Desktop
> Connect Claude Desktop to Cognee MCP on macOS or Windows.
# 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](https://claude.ai/download) installed
* Cognee MCP server available (see [Quickstart](/cognee-mcp/mcp-quickstart) or [Local Setup](/cognee-mcp/mcp-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
```bash theme={null}
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.
Choose the mode that matches your setup:
Point the MCP server at your Cognee Cloud tenant using your API Base URL and API key from the [API Keys](/cognee-cloud/ui/api-keys) page:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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`](https://www.npmjs.com/package/mcp-remote) bridge to reach an HTTP/SSE URL. This requires [Node.js](https://nodejs.org) (for `npx`).
```json theme={null}
{
"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:
```json theme={null}
{
"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](/cognee-mcp/mcp-local-setup).
Fully quit and reopen Claude Desktop. On macOS, use **Cmd + Q** (not just closing the window) to ensure the app reloads the config.
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](#troubleshooting) below.
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
* 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`.
* Confirm the `--serve-url` (or `COGNEE_BASE_URL`) value matches exactly the API Base URL on your [API Keys](/cognee-cloud/ui/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.
* 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](/cognee-mcp/mcp-local-setup).
* 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.
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?
Get support and connect with other developers using Cognee MCP.