Graphiti MCP

# Troubleshooting Guide ## Docker Issues ### Docker daemon not running (Windows) **Error Message**: ``` error during connect: in the default daemon configuration on Windows, the docker client must be run with elevated privileges to connect: Get "http://%2F%2F.%2Fpipe%2Fdocker_engine/...": open //./pipe/docker_engine: The system cannot find the file specified. ``` **Solutions**: 1. **Start Docker Desktop**: - Check your system tray (bottom-right corner) for the Docker Desktop icon - If you don't see it, Docker Desktop is not running - Open Docker Desktop from the Start menu - Wait for Docker Desktop to fully start (the whale icon should be steady, not animating) - You should see "Docker Desktop is running" in the system tray 2. **Verify Docker is working**: ```powershell docker ps ``` If this command works without errors, Docker is running correctly. 3. **Run PowerShell as Administrator** (if Docker Desktop is running but still getting errors): - Right-click PowerShell - Select "Run as Administrator" - Navigate to your project: `cd C:\Users\hansi_iq5v8g0\Desktop\graphiti_mcp` - Try again: `docker compose up` 4. **Check Docker Desktop Settings**: - Open Docker Desktop - Go to Settings → General - Ensure "Use the WSL 2 based engine" is checked (if you have WSL 2) - Or ensure "Use Hyper-V" is checked (if using Hyper-V) ### Docker Compose Warnings **Warning**: `The "OPENAI_API_KEY" variable is not set. Defaulting to a blank string.` **Solution**: This is now expected behavior. The server will use `OPENROUTER_API_KEY` if available, or `OPENAI_API_KEY` if provided. Make sure you have at least one set in your `.env` file: ```dotenv OPENROUTER_API_KEY=sk-or-your-key-here ``` **Warning**: `the attribute 'version' is obsolete` **Solution**: This has been fixed in the latest `docker-compose.yml`. The version field has been removed as it's no longer needed in newer Docker Compose versions. ## API Key Issues ### "OPENROUTER_API_KEY or OPENAI_API_KEY not found" **Solution**: 1. Create a `.env` file in the project root if it doesn't exist: ```powershell Copy-Item env.example .env ``` 2. Edit the `.env` file and add your API key: ```dotenv OPENROUTER_API_KEY=sk-or-your-key-here MODEL_NAME=openai/gpt-4o-mini ``` 3. Get an OpenRouter API key at: https://openrouter.ai/keys 4. Verify the key is loaded: ```powershell Get-Content .env ``` ## Neo4j Connection Issues ### "Connection refused" to Neo4j **Solutions**: 1. Check if Neo4j container is running: ```powershell docker ps ``` You should see `graphiti-neo4j` in the list. 2. Check Neo4j logs: ```powershell docker logs graphiti-neo4j ``` 3. Test Neo4j connection: ```powershell docker exec -it graphiti-neo4j cypher-shell -u neo4j -p demodemo ``` If this works, Neo4j is running correctly. 4. Wait for Neo4j to fully initialize: - Neo4j can take 10-30 seconds to start - The MCP server will wait for Neo4j to be healthy before starting - Check health status: `docker compose ps` ## MCP Server Issues ### MCP Server not starting **Solutions**: 1. Check MCP server logs: ```powershell docker compose logs mcp-server ``` 2. Verify all environment variables are set: ```powershell docker compose config ``` 3. Test the server manually (outside Docker): ```powershell # Make sure Neo4j is running first uv run graphiti_mcp_server.py --transport sse --port 8000 ``` ### Cursor not connecting to MCP server **Solutions**: 1. Verify the server is running: ```powershell curl http://localhost:8000/sse ``` 2. Check your `mcp.json` file location: - Windows: `%APPDATA%\Cursor\User\globalStorage\mcp.json` - Or: `C:\Users\<username>\.cursor\mcp.json` 3. Verify the URL in `mcp.json`: ```json { "mcpServers": { "Graphiti": { "url": "http://localhost:8000/sse" } } } ``` 4. Restart Cursor after updating `mcp.json` ## Port Conflicts ### Port 8000 already in use **Error**: `Bind for 0.0.0.0:8000 failed: port is already allocated` **Solutions**: 1. Find what's using port 8000: ```powershell netstat -ano | findstr :8000 ``` 2. Change the port in `docker-compose.yml`: ```yaml ports: - "8001:8000" # Use 8001 instead ``` 3. Update `mcp.json` to match: ```json { "mcpServers": { "Graphiti": { "url": "http://localhost:8001/sse" } } } ``` ## General Tips 1. **Always check Docker Desktop is running** before using `docker compose` 2. **Wait for services to fully start** - Neo4j can take time to initialize 3. **Check logs** when things don't work: `docker compose logs` 4. **Verify your `.env` file** has the correct API keys 5. **Restart Cursor/Claude** after updating MCP configuration files