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

1. Open the config file

   macOS

   open ~/Library/Application\ Support/Claude/
   

   Open claude_desktop_config.json in your editor of choice.

   Windows

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

2. Add the Cognee server

   Choose the mode that matches your setup:

   Cloud-connected

   Point the MCP server at your Cognee Cloud tenant with --api-url and --api-token, using your API Base URL and API key from the API Keys page. These are the flags the MCP tools use to reach your tenant. This runs via uvx (requires uv — see Troubleshooting if uvx isn’t found) and is the same config the in-product Integrations page generates:

   {
     "mcpServers": {
       "cognee": {
         "command": "uvx",
         "args": [
           "cognee-mcp@latest",
           "--api-url", "https://your-tenant.aws.cognee.ai",
           "--api-token", "your-cognee-cloud-api-key"
         ]
       }
     }
   }
   

   Standalone (local)

   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.

   Remote / self-hosted URL

   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.

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

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

5. 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.
• For the uvx (Cloud-connected) config: confirm uv is installed — run uvx --version in a terminal. On Windows, a missing uv install is the most common cause ('uvx' is not recognized...); install it with powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" and restart both your terminal and Claude Desktop.
• For the standalone cognee-mcp command form: check that it’s on your PATH — run which cognee-mcp (macOS/Linux) or where cognee-mcp (Windows). 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 --api-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 --api-url endpoint.

Need Help?

Join Our Community

Get support and connect with other developers using Cognee MCP.