How to add Graphiti MCP to Windsurf

Temporal knowledge-graph memory for agents: add episodes and search facts over FalkorDB or Neo4j, from Zep. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 28k★ · http · apikey · official

Windsurf config for Graphiti MCP

git clone https://github.com/getzep/graphiti.git && cd graphiti/mcp_server && docker compose up

{
  "mcpServers": {
    "graphiti-mcp": {
      "serverUrl": "http://localhost:8000/mcp/"
    }
  }
}

Remote server — no local install needed. Restart the client after saving the config.

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Graphiti MCP config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Graphiti MCP's tools become available to Cascade.

Before you start

Docker and Docker Compose (default FalkorDB combined container)
An LLM provider API key — OPENAI_API_KEY by default; Anthropic, Gemini, Groq, and Azure OpenAI are also supported
Python 3.10+ and uv only if running the server standalone against an external database
Neo4j 5.26+ if you choose it over the bundled FalkorDB

What Graphiti MCP can do in Windsurf

add_memory

Add an episode (text, JSON, or message format) to the graph; queued for async LLM extraction.

add_triplet

Insert a single source-fact-target triplet directly, bypassing extraction.

search_nodes

Search entity nodes with entity_types and center_node_uuid filters.

search_memory_facts

Search facts (edges) with edge_types, center node, and valid_at/invalid_at date-range filters.

summarize_saga

Generate or refresh the running summary of a saga's episodes.

build_communities

Detect entity communities and produce higher-level community summaries.

get_episode_entities

Trace provenance: which entities and facts specific episodes created.

delete_entity_edge

Delete an entity edge from the graph.

Security

Self-hosted: graph data stays in your FalkorDB/Neo4j instance, but every episode's content is sent to the configured LLM provider (OpenAI by default) for entity extraction. API keys live in a server-side .env file, and anonymous telemetry is on unless you set GRAPHITI_TELEMETRY_ENABLED=false.

Graphiti MCP + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Graphiti MCP config there under the "mcpServers" key and restart the client.

Is Graphiti MCP safe to use with Windsurf?

Is the Graphiti MCP server free?

Yes — Apache-2.0 and fully self-hosted, with FalkorDB bundled in the default container. Your real cost is LLM usage: each episode triggers multiple extraction/dedup/summarization calls to your configured provider, which is also why the SEMAPHORE_LIMIT concurrency setting matters.

How is this different from a vector-store memory server?

Graphiti builds an entity/relationship graph with bi-temporal validity rather than storing chunks. You get structured facts with valid_at/invalid_at history, date-range queries, community summaries, and provenance tracing — at the price of running a graph database and paying for extraction LLM calls.

Why am I seeing 429 rate-limit errors during ingestion?

Your SEMAPHORE_LIMIT is too high for your LLM tier. The default of 10 assumes roughly OpenAI Tier 3 (500 RPM); the README suggests 1-2 for free tiers and up to 20-50 for Tier 4. Each episode fans out into several concurrent LLM requests, so lower it until 429s stop.

View repo Full Graphiti MCP page