Neo4j Mcp Server Free

Neo4j 5.17.0 Cypher MCP 2026-07-28 Free tier MIT

Every assistant conversation begins from nothing. You explain the project again, re-establish who the people are, restate the constraint you agreed on last Tuesday. Retrieval-augmented setups soften this by pulling back text that resembles the current question — which is a real improvement, and also completely blind to the fact that the constraint you agreed on supersedes the one from the week before.

Facts that relate to other facts want a graph. This repository is a working setup for using a free Neo4j 5.17 instance on freebase.cloud as durable, queryable memory for an MCP-connected agent, with the Cypher and the modelling conventions that make it hold up past week three.

The example graph is a research assistant's memory: papers, authors, concepts, claims the agent has extracted, and — importantly — the agent's own observations about what it did and when.

---

The idea in one paragraph

Nodes are things the agent should remember. Relationships are the reason two things belong in the same thought. Writing memory means MERGE, never CREATE, so that recording the same fact twice is a no-op instead of a duplicate. Recall is a traversal from an anchor node outward, bounded by hop count, which means the agent retrieves a neighbourhood rather than a ranked list of paragraphs. The whole thing is four MCP tool calls away from any client that speaks the protocol.

---

Four sessions with a graph

Session 1 — the agent learns something

MERGE (p:Paper {doi: '10.1145/3379597.3387473'})
  ON CREATE SET p.title = 'On the Naturalness of Fuzzing', p.year = 2020
MERGE (c:Concept {name: 'coverage-guided fuzzing'})
MERGE (p)-[:DISCUSSES]->(c);

Two nodes and an edge. Run it again tomorrow and nothing changes — MERGE matches the existing node by its unique property and moves on. This is the single most important habit in an agent-written graph, because agents re-derive the same fact constantly. Everything in this section runs unmodified on the free Neo4j engine.

Session 2 — a second paper, and the graph starts paying rent

MERGE (p:Paper {doi: '10.1109/ICSE48619.2023.00042'})
  ON CREATE SET p.title = 'Seed Scheduling Revisited', p.year = 2023
MERGE (c:Concept {name: 'coverage-guided fuzzing'})
MERGE (p)-[:DISCUSSES]->(c);

// Now: what else touches the concept I was just reading about?
MATCH (:Paper {doi: '10.1109/ICSE48619.2023.00042'})-[:DISCUSSES]->(c:Concept)<-[:DISCUSSES]-(other:Paper)
RETURN other.title, other.year ORDER BY other.year DESC;

Nobody wrote a "related papers" table. The relationship was already there; the second-hop query just read it. That is the entire value proposition of a graph in one query.

Session 3 — the agent records what it believes, and why

MATCH (p:Paper {doi: '10.1109/ICSE48619.2023.00042'})
MERGE (claim:Claim {text: 'Seed scheduling dominates mutation strategy on large corpora'})
  ON CREATE SET claim.confidence = 0.6, claim.first_seen = datetime()
MERGE (claim)-[:SUPPORTED_BY]->(p)
MERGE (obs:Observation {id: randomUUID()})
  SET obs.at = datetime(), obs.by = 'research-assistant', obs.note = 'extracted from section 4.2'
MERGE (obs)-[:ABOUT]->(claim);

Claim and Observation as separate node types is the part people skip and then regret. A claim is what the agent thinks is true. An observation is the event of it thinking so. Keeping them apart means you can revise a claim without losing the trail of how it got there, and you can ask "what did I conclude in March" as a first-class query.

Session 4 — recall, bounded

MATCH path = (anchor:Concept {name: 'coverage-guided fuzzing'})-[*1..2]-(neighbour)
WHERE NOT neighbour:Observation
RETURN DISTINCT labels(neighbour)[0] AS kind,
       coalesce(neighbour.title, neighbour.name, neighbour.text) AS what,
       length(path) AS hops
ORDER BY hops, kind
LIMIT 25;

[*1..2] is doing the load-bearing work. Unbounded variable-length patterns on a well-connected graph will happily traverse everything and hand your model a context window full of nothing. Two hops is usually the right answer for recall; three is the most you should let an agent write without thinking about it.

---

Why a graph rather than a vector store

Both are legitimate. They fail differently, and the failure modes matter more than the features:

	Vector store	Property graph
Retrieves	Text that resembles the query	Entities connected to an anchor
Handles "who else"	Poorly — similarity is not adjacency	Natively, it is one hop
Handles contradiction	Returns both, undifferentiated	You can model supersession explicitly
Handles "when did I learn this"	Only if you stored it as metadata and filter on it	It is a property or an edge
Needs an embedding model	Yes	No
Handles fuzzy phrasing	Very well	Badly, unless you add a text index

The honest summary: vector search is better at finding the right document; a graph is better at answering questions about relationships between things you already identified. Real systems tend to use both — semantic retrieval to find the entry point, then a graph traversal to expand it. Neo4j has vector indexes for exactly this reason, and if your access pattern is purely "find me similar text", a dedicated vector database will do it with less ceremony.

---

Connecting

Create a session on freebase.cloud with the Neo4j engine. In Settings → MCP → New Token, pick the connection and copy the URL:

export FREEBASE_MCP_URL="https://freebase.cloud/api/mcp/YOUR_TOKEN"

The token lives in the URL path. There is no Authorization header to configure anywhere, which is convenient and also means the URL should be handled like a password.

Cypher's native transport is Bolt, on port 7687 — that is where cypher-shell, Neo4j Browser and the official drivers live, and the instance page documents what compatibility exists. Everything in this repository takes the other route: MCP over streamable HTTP, one endpoint, no driver installed. Details for the instance itself are on the Neo4j engine page.

---

The tools

Name the connection memory when you create it and you get:

• memory_query — runs Cypher and returns rows. Read queries: MATCH, CALL, RETURN.
• memory_store — runs writing Cypher: MERGE, CREATE, SET, DELETE, constraint DDL.
• memory_list_tables — enumerates node labels and relationship types. Cypher has no tables; this is the label inventory, and it is what the model reaches for first in a cold conversation.
• memory_annotate_table — attaches a description to a label so the model knows the shape.

Annotating Claim with "the agent's current belief; confidence is 0–1 and gets revised, never overwritten silently; always SUPPORTED_BY at least one Paper" removes a whole category of malformed writes. Do it once per label after you settle the schema.

---

Modelling rules for a graph an agent writes to

Learned the tedious way:

1. Constrain every identity property before the first write. CREATE CONSTRAINT ... IS UNIQUE is what makes MERGE fast and correct. Without it MERGE does a label scan and, under concurrency, can still duplicate. See examples/schema.cypher.
2. Never let the agent invent labels. Fix the label set up front. An agent left to its own devices will produce Person, Author, Researcher and person inside a month, and none of your queries will match all four.
3. Relationship type carries the meaning; properties carry the detail. [:CITES {section: 4}] is right. [:RELATED {kind: 'cites'}] is a graph pretending to be a key-value store, and it defeats the index that makes traversal fast.
4. Direction is a modelling decision, not a formality. (:Paper)-[:CITES]->(:Paper) means something. Traverse without a direction arrow when you want both ways; store it directed.
5. Timestamp writes with datetime(), not a string. Temporal types sort and compare properly; ISO strings mostly do, until a timezone shows up.
6. Delete with DETACH DELETE. Plain DELETE on a node with relationships throws, which confuses models into retrying with progressively worse queries.

---

APOC and graph algorithms

The instance documentation lists APOC availability — apoc.create, apoc.path and apoc.export among them — and Graph Data Science routines for PageRank, community detection, shortest path and centrality. Two that earn their keep in a memory graph:

// Expand outward but refuse to walk through Observation nodes or leave the subgraph
CALL apoc.path.subgraphNodes(anchor, {
  maxLevel: 3,
  labelFilter: '-Observation',
  relationshipFilter: 'DISCUSSES|SUPPORTED_BY|CITES'
}) YIELD node
RETURN node;

// Which concepts sit between the most pairs of papers? Good "what is this graph about" answer.
MATCH (a:Paper), (b:Paper) WHERE elementId(a) < elementId(b)
MATCH p = shortestPath((a)-[:DISCUSSES*..4]-(b))
UNWIND [n IN nodes(p) WHERE n:Concept] AS bridge
RETURN bridge.name, count(*) AS on_paths ORDER BY on_paths DESC LIMIT 10;

The second one is deliberately expensive. Run it on a graph of a few thousand nodes and it is instructive; run it on a million and you will be waiting. Check PROFILE before you let an agent schedule anything like it.

---

Where this is the wrong choice

• Bulk analytics over flat rows. Counting events per day across ten million records is a columnar workload. Graph traversal has no advantage there and considerable overhead.
• Anything write-heavy and append-only. Logs, metrics, telemetry — those are time-series shapes. Every one of them will be faster and cheaper in InfluxDB or ClickHouse.
• Short-lived state. Conversation scratch, rate limit counters, a queue — Redis, with a TTL. A graph with no traversal in its future is an expensive dictionary.
• When you don't yet know the entities. Graph modelling requires you to commit to what a node is. If you are still at the "dump the transcripts somewhere and see what's in them" stage, index the text first and build the graph from what you find.

A useful test: if you can't name a query that goes two hops, you probably don't need a graph yet.

---

Client configuration notes

Client	Where	The one thing that trips people up
Claude Code	claude mcp add --transport http memory <URL>	A url entry with no "type" in .mcp.json is a hard failure, not a warning
Claude Desktop / web	Settings → Connectors → Add custom connector	The desktop JSON config cannot hold remote HTTP servers at all; free accounts get one custom connector
Windsurf	~/.codeium/windsurf/mcp_config.json	The key is serverUrl, not url
Zed	settings.json	Top-level key is context_servers, not mcpServers
Gemini CLI	gemini mcp add --transport http memory <URL>	In settings.json use httpUrl; plain url means SSE and will silently misbehave
Cline	MCP settings JSON	"type": "streamableHttp" — camelCase
Roo Code	.roo/mcp.json	"type": "streamable-http" — kebab-case. Same idea, different spelling, no fallback

The walkthrough for Claude specifically lives in the Claude-to-Neo4j guide.

---

Free tier, honestly

Neo4j 5.17.0 with the full Cypher clause set, uniqueness constraints, range and text indexes, APOC procedures and the GDS routines. The free tier is scoped for development, prototyping and small production workloads — an agent's memory graph, a demo, a side project, a recommendation prototype. Current node and relationship limits are shown in the dashboard rather than promised here.

Neo4j Aura is where you go for a cluster, backups you can point to in an audit, and a support contract. This is where you go to have a graph in five minutes without a procurement conversation.

---

Reference

• Cypher manual — clause reference and the PROFILE / EXPLAIN documentation
• APOC user guide
• Graph Data Science library
• MCP specification
• Free Neo4j cloud instance

Contributions welcome — especially traversal patterns that turned out to be useful in a real agent loop.

---

freebase.cloud is an independent service and is not affiliated with Neo4j, Inc., Anthropic, Google, InfluxData, ClickHouse, Inc., Redis Ltd. or Codeium.