Graphiti MCP

# Quick Start Guide ## Prerequisites 1. **Python 3.10+** installed 2. **OpenRouter API Key** (recommended) or **OpenAI API Key** 3. **Neo4j Database** - Use free cloud instance (Neo4j Aura) or any Neo4j instance ## Quick Setup (5 minutes) ### Step 1: Install Dependencies **Option A: Using uv (Recommended)** ```powershell # Install uv if you don't have it (Windows) irm https://astral.sh/uv/install.ps1 | iex # Install project dependencies uv sync ``` **Option B: Using pip** ```powershell pip install mcp neo4j openai python-dotenv fastapi uvicorn sse-starlette ``` ### Step 2: Set Up Neo4j (Free Cloud Instance) **Easiest Option: Use Neo4j Aura (Free)** 1. Go to https://neo4j.com/cloud/aura/ and sign up for a free account 2. Create a free database instance 3. Copy your connection details: - **URI**: Something like `neo4j+s://xxxxx.databases.neo4j.io` - **Username**: Usually `neo4j` - **Password**: The password you set **Alternative: Use Existing Neo4j Instance** If you already have a Neo4j instance running (local or remote), use its connection details. ### Step 3: Configure Environment Create a `.env` file in the project directory: **Windows PowerShell:** ```powershell Copy-Item env.example .env notepad .env ``` **Or manually create `.env` with:** ```dotenv # Neo4j Database Configuration # For Neo4j Aura, use the URI format: neo4j+s://xxxxx.databases.neo4j.io # For local Neo4j, use: bolt://localhost:7687 NEO4J_URI=neo4j+s://xxxxx.databases.neo4j.io NEO4J_USER=neo4j NEO4J_PASSWORD=your_password_here # OpenRouter API Configuration (Recommended) OPENROUTER_API_KEY=sk-or-your-key-here MODEL_NAME=openai/gpt-4o-mini # Alternative: OpenAI API Configuration # OPENAI_API_KEY=sk-your-key-here # MODEL_NAME=gpt-4o-mini ``` **Important**: - Replace the Neo4j connection details with your actual values - Get OpenRouter API key at: https://openrouter.ai/keys - For Neo4j Aura, the URI format is `neo4j+s://xxxxx.databases.neo4j.io` (note the `+s` for secure connection) ### Step 4: Run MCP Server **For Cursor (SSE transport):** ```powershell uv run graphiti_mcp_server.py --transport sse --port 8000 ``` **Or using Python directly:** ```powershell python graphiti_mcp_server.py --transport sse --port 8000 ``` **For Claude (stdio transport):** ```powershell uv run graphiti_mcp_server.py --transport stdio ``` The server will connect to your Neo4j instance and start listening for connections. ### Step 5: Configure Clients #### Cursor Add to your `mcp.json` (usually at `%APPDATA%\Cursor\User\globalStorage\mcp.json`): ```json { "mcpServers": { "Graphiti": { "url": "http://localhost:8000/sse" } } } ``` #### Claude Desktop Add to `claude_desktop_config.json`: ```json { "mcpServers": { "graphiti": { "transport": "stdio", "command": "uv", "args": [ "run", "--directory", "C:\\Users\\hansi_iq5v8g0\\Desktop\\graphiti_mcp", "graphiti_mcp_server.py", "--transport", "stdio" ] } } } ``` **Important**: Update the `--directory` path to your actual project path. ## Testing the Server ### Option 1: Web UI (Recommended for Testing) Start the web UI to interact with the server through a beautiful interface: **Windows:** ```powershell .\run-web-ui.ps1 ``` **Linux/Mac:** ```bash ./run-web-ui.sh # Or directly: python web_ui_server.py ``` Then open your browser to: **http://localhost:8081** (or the port specified) **Note**: If port 8081 is in use, you can specify a different port: ```powershell python web_ui_server.py 3000 ``` The web UI provides an intuitive interface to: - Store memories with tags and metadata - Search and retrieve memories - Get synthesized context - Create relationships between memories - Execute Cypher queries - Browse all stored memories ### Option 2: MCP Tools in Cursor/Claude Once running, you can test the server by using the MCP tools in Cursor or Claude: 1. **Store a memory**: "Remember that I prefer Python for data science projects" 2. **Retrieve memories**: "What do you remember about my preferences?" 3. **Get context**: "Give me context about data science" ## Troubleshooting ### "Connection refused" to Neo4j **Solutions**: 1. **Check your `.env` file** has the correct Neo4j connection details 2. **For Neo4j Aura**: Make sure you're using the correct URI format with `neo4j+s://` 3. **Test connection manually**: ```powershell python -c "from neo4j import GraphDatabase; driver = GraphDatabase.driver('your_uri_here', auth=('neo4j', 'your_password')); driver.verify_connectivity(); print('Connected!')" ``` ### "OPENROUTER_API_KEY or OPENAI_API_KEY not found" **Solutions**: 1. Check your `.env` file exists in the project root 2. Verify the key is set: `Get-Content .env` (PowerShell) 3. Get an OpenRouter API key at: https://openrouter.ai/keys ### MCP Server not connecting **Solutions**: 1. **For SSE**: Check the server is running on port 8000: ```powershell curl http://localhost:8000/sse ``` 2. **Check server logs** for error messages 3. **Restart Cursor** after updating `mcp.json` ### Neo4j Aura Connection Issues **Common Issues**: - **Wrong URI format**: Use `neo4j+s://` not `bolt://` for Aura - **Firewall**: Make sure your IP is whitelisted in Aura settings - **Password**: Double-check your password is correct ## Next Steps - Read the full [README.md](README.md) for detailed documentation - Explore the available MCP tools - Build relationships between memories using `create_relationship` - Query the graph directly using `search_graph` ## Running Without Neo4j (Development Mode) If you want to test the server without Neo4j, you can modify the code to use an in-memory store, but this is not recommended for production use.