Integrating Gemini CLI with Graphiti MCP: A Practical Guide

Before configuring, complete these prerequisites:

Install Gemini CLI:

# Via Homebrew (macOS)
brew install gemini
# Or via npm
npm install -g @gemini-cli/core

Obtain and start Graphiti MCP Server: Choose one of the following methods to start Graphiti.

Docker (recommended):

# In the Graphiti project root
docker-compose up -d

Build from source:

# Ensure uv is installed
uv run graphiti_mcp_server.py --transport sse --model gpt-4o

Set environment variables: Graphiti requires access to the OpenAI API and Neo4j database. Ensure these are configured:
```
export OPENAI_API_KEY="sk-..."
export NEO4J_PASSWORD="your-neo4j-password"
```
Confirm the service port: By default, Graphiti runs on localhost:8000. Verify it is running by checking these endpoints:
- SSE endpoint: http://localhost:8000/sse
- WebSocket endpoint: http://localhost:8000/ws

3. Configuration Method A: Gemini CLI Hosts Graphiti (stdio)

This method runs Graphiti as a child process of Gemini CLI, suitable for quick local integration.

Open Gemini CLI's configuration file at ~/.gemini/settings.json and add the following mcpServers configuration:

{
  "mcpServers": {
    "graphiti": {
      "command": "uv",
      "args": ["run", "graphiti_mcp_server.py", "--model", "gpt-4o", "--transport", "stdio"],
      "cwd": "/ABSOLUTE/PATH/TO/graphiti-mcp-server",
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "NEO4J_PASSWORD": "..."
      },
      "trust": true
    }
  }
}

command & args: Specifies the command to start the Graphiti service.
cwd: Must be the absolute path to the Graphiti MCP Server project.
env: Passes required environment variables.
Advantages: Simple configuration, zero port conflicts, no additional network setup needed.

After configuration, restart Gemini CLI. Run /mcp to verify that graphiti is connected.

4. Configuration Method B: Gemini CLI Connects to a Running Graphiti Service (SSE)

If Graphiti is already running as an independent service, use this method.

In ~/.gemini/settings.json, add:

{
  "mcpServers": {
    "graphiti": {
      "url": "http://127.0.0.1:8000/sse",
      "timeout": 8000,
      "trust": true
    }
  }
}

url: This is the critical field. Use url, not httpUrl; Gemini CLI will then connect via GET with text/event-stream content type, as required by SSE.
timeout: Set a longer timeout (e.g., 8000ms) to accommodate network latency.
headers: If your remote service requires authentication, add an Authorization header here, for example: "headers": { "Authorization": "Bearer your-token" }.

Verify the connection:

Test the SSE stream:
```
curl -N http://127.0.0.1:8000/sse | head
```
If you see continuous heartbeat events (such as event: ping), the SSE service is running correctly.
Check in Gemini CLI: Start Gemini CLI and run /mcp desc graphiti. If it lists Graphiti's tools, the connection is successful.

5. Common Errors & Solutions

Symptom	Possible Cause	Solution
`Error 405 Method Not Allowed`	CLI defaults to POST for SSE endpoints.	Change `httpUrl` to `url` in settings.json, or ensure the Graphiti endpoint accepts POST.
`Disconnected (0 tools cached)`	Graphiti service is not running or the endpoint URL is incorrect.	Check `docker ps` or `lsof -Pni :8000` to confirm the service is running, and verify the URL in settings.json.
`Timeout`	The SSE persistent connection is interrupted by a firewall or reverse proxy (e.g., Nginx).	Increase the `timeout` value; check firewall rules; disable Nginx proxy buffering (`proxy_buffering off;`).
Port conflict with multiple instances	Multiple Graphiti instances or other services are using port 8000.	Change Graphiti's startup port (e.g., `GRAPHITI_PORT=8001`) and add multiple node configurations in settings.json.

6. Quick Diagnostic Commands

These commands help diagnose issues:

Check the Graphiti process and port usage:

# See which process is using port 8000
lsof -Pni :8000

Test SSE connectivity:

# Monitor the SSE event stream continuously
curl -N http://127.0.0.1:8000/sse | head

Enable Gemini CLI debug mode:

# Add --debug when starting to see detailed logs
gemini --debug

7. Summary

The integration process has three steps: start Graphiti, add the correct url or command to ~/.gemini/settings.json, then restart Gemini CLI.