codecov PyPI License

grafeo-mcp

MCP server that exposes GrafeoDB - an embedded graph database - to AI agents via the Model Context Protocol.

One install, zero infrastructure. The MCP server is the database.

Features

23 tools - graph CRUD, GQL queries, batch import, full-text search, vector search, MMR, hybrid retrieval, PageRank, Dijkstra, Louvain and more
3 resources - graph://schema, graph://stats, graph://nodes/{id}
4 workflow prompts - guide agents through exploration, knowledge extraction, graph analysis and similarity search
GQL with Cypher auto-normalization - agents trained on Cypher syntax work out of the box
Schema-first - agents discover the graph structure before querying
Token-aware - all tools have limit params and truncate large results
Embedded - no separate database server to manage

Quickstart

# Install
uv tool install grafeo-mcp

# Or with pip
pip install grafeo-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "grafeo": {
      "command": "grafeo-mcp",
      "env": {
        "GRAFEO_DB_PATH": "/path/to/your/graph.db"
      }
    }
  }
}

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "grafeo": {
      "command": "grafeo-mcp",
      "env": {
        "GRAFEO_DB_PATH": "./graph.db"
      }
    }
  }
}

VS Code / Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "grafeo": {
      "command": "grafeo-mcp",
      "env": {
        "GRAFEO_DB_PATH": "${workspaceFolder}/graph.db"
      }
    }
  }
}

HTTP transport

For remote or multi-client setups:

grafeo-mcp streamable-http

Environment Variables

Variable	Description	Default
`GRAFEO_DB_PATH`	Path to the database file. Creates it if it doesn't exist	In-memory

Tools

Query

Tool	Description
`execute_gql`	Run GQL queries (Cypher syntax auto-normalized to GQL)

Graph CRUD & Traversal

Tool	Description
`create_node`	Create a node with labels and properties
`create_edge`	Create a directed edge between two nodes
`get_node`	Retrieve a node by ID
`update_node`	Update properties on an existing node
`delete_node`	Delete a node (with optional detach)
`update_edge`	Update properties on an existing edge
`delete_edge`	Delete an edge by ID
`get_neighbors`	Explore a node's neighborhood (1-hop)
`search_nodes_by_label`	Find nodes by label with pagination
`graph_info`	Schema, stats, labels, edge types, indexes

Batch Import

Tool	Description
`batch_import`	Bulk-create nodes and edges from JSON arrays

Full-Text Search

Tool	Description
`create_text_index`	Create a full-text search index on a property
`search_text`	Keyword search over indexed string properties

Vector Search

Tool	Description
`vector_search`	k-NN similarity search (HNSW)
`mmr_search`	Diversity-aware search (Maximal Marginal Relevance)
`create_vector_index`	Create HNSW index on a label + property
`vector_graph_search`	Hybrid: vector search + graph neighborhood expansion

Graph Algorithms

Tool	Description
`pagerank`	Rank nodes by importance
`dijkstra`	Shortest weighted path between two nodes
`louvain`	Community detection (Louvain modularity)
`betweenness_centrality`	Find bridge/bottleneck nodes
`connected_components`	Find disconnected subgraphs

Resources

URI	Description
`graph://schema`	Rich schema: labels, properties, edge types
`graph://stats`	Counts, memory, disk, config info
`graph://nodes/{node_id}`	Node details + connection summary

Prompts

Prompt	Description
`explore_graph`	Guided exploration of the graph structure
`knowledge_extraction`	Extract entities and relationships from text
`graph_analysis`	Structural analysis: communities, PageRank, hubs
`similarity_search`	Vector-powered semantic search with graph context

Which tool when?

I want to...	Use this tool	Not this
Add a single node	`create_node`	`execute_gql`, `batch_import`
Add a single edge	`create_edge`	`execute_gql`
Load many nodes and edges at once	`batch_import`	`create_node` in a loop
Look up a node by ID	`get_node`	`execute_gql`
Update a node's properties	`update_node`	`execute_gql`
Delete a node	`delete_node`	`execute_gql`
Update an edge's properties	`update_edge`	`execute_gql`
Delete an edge	`delete_edge`	`execute_gql`
Browse nodes of a type	`search_nodes_by_label`	`execute_gql`
Explore one hop from a node	`get_neighbors`	`execute_gql`
Run a complex or multi-hop query	`execute_gql`	multiple `get_neighbors`
Search by keyword in text	`search_text`	`execute_gql`
Find similar nodes by embedding	`vector_search`	`execute_gql`
Find similar nodes + graph context	`vector_graph_search`	`vector_search` + `get_neighbors`
Find the most important nodes	`pagerank`	`execute_gql`
Find shortest path between two nodes	`dijkstra`	`execute_gql`
Detect communities	`louvain`	`execute_gql`
Understand the graph before querying	`graph_info`	`search_nodes_by_label`

Batch reference syntax

The batch_import tool lets edges reference nodes created in the same batch using @N notation, where N is the zero-based index into the nodes array:

batch_import(
    nodes=[
        {"labels": ["Person"], "properties": {"name": "Alice"}},  # @0
        {"labels": ["Person"], "properties": {"name": "Bob"}},    # @1
    ],
    edges=[
        {"source_ref": "@0", "target_ref": "@1", "edge_type": "KNOWS"},
    ],
)

You can also mix batch references with existing node IDs: {"source_ref": "@0", "target_ref": 42, ...}.

Cypher normalization

The execute_gql tool automatically normalizes common Cypher syntax to GQL so agents trained on Cypher work out of the box. Currently the following transformations are applied:

Cypher keyword	GQL equivalent
`CREATE`	`INSERT`

Keywords that are shared between Cypher and GQL (such as MATCH, RETURN, WHERE, WITH, LIMIT, DETACH DELETE) pass through unchanged. Cypher-only keywords like MERGE or OPTIONAL MATCH are not supported and will produce a clear error message from the query engine.

Development

git clone https://github.com/GrafeoDB/grafeo-mcp
cd grafeo-mcp
uv sync
uv run pytest          # Run tests
uv run ruff check .    # Lint
uv run ruff format .   # Format
uv run ty check        # Type check

License

Apache-2.0