This server provides a GraphRAG (Graph-based Retrieval Augmented Generation) engine for indexing documents, building knowledge graphs, and querying/analyzing them through multiple search modes and graph exploration.
Keyword Search (keyword_lookup): Exact BM25-based retrieval for specific terms, ticker symbols (e.g., ASTS, RKLB), acronyms, or product names.
Entity Relationship Search (entity_connections): Query the knowledge graph to discover entities, their relationships, competitive landscapes, and connections within the corpus.
Thematic Overview (thematic_overview): Retrieve high-level patterns, trends, and macro narratives across the entire document corpus — useful for sector analysis and broad topic exploration.
Entity Graph Exploration (explore_entity_graph): Traverse the knowledge graph from a specific named entity, exploring direct connections up to 3 hops away — useful for building reasoning chains or verifying facts.
Corpus Statistics (get_corpus_stats): Retrieve health and scale metrics including counts of documents, chunks, entities, and relationships.
Index Documents: Ingest local documents into a knowledge graph using a full ML indexing pipeline.
Manage Databases: Initialize, list, check status, and delete knowledge base entries via CLI.
Deploy to Cloud: Supports deployment to Fly.io and AWS (ECR, S3, App Runner) with a lightweight ~1GB query server footprint.
Integrate with MCP-compatible agents (e.g., Claude Desktop, Cursor) to give AI assistants access to your document knowledge base.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@GraphRAG Llama Index MCP Server search for recent acquisitions in the AI chip industry"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Full-stack GraphRAG engine optimized for local indexing and lightweight cloud querying. Built on DuckDB, LlamaIndex, and the Model Context Protocol (MCP).
This project implements a Decoupled Architecture:
Indexer (Image A): Heavy-duty ML environment (PyTorch, GLiNER) for local graph construction.
Query (Image B): Lightweight API environment (Node.js, DuckDB) for fast cloud deployment (~1GB footprint).
Related MCP server: Graforest MCP
# Build specialized images via Docker Compose
docker compose buildLoad the shell aliases for the fastest workflow:
macOS (Zsh): source .graphrag-alias.zsh
WSL/Bash: source .graphrag-alias.sh
PowerShell: . .\.graphrag-alias.ps1
# 1. Initialize a database entry
graphrag start my_project --source /app/documents/source_files
# 2. Run the ingestion pipeline (Indexer Image)
graphrag index my_project [--reset] [--prune]# CLI Search (Query Image)
graphrag search my_project "What are the common themes?"
# Start MCP Server for Agents
docker compose up querydeployment/fly/: Scripts for zero-latency hosting on Fly.io (optimized for free-tier fly-machines).
deployment/aws/: Infrastructure scripts for ECR, S3 backups, and App Runner deployments.
Copy .env.example and set:
OPENAI_API_KEY: For LLM reasoning and extraction.
DOCUMENTS_HOME: Absolute path to your local data folder (mapped to /app/documents in Docker).
Tweak these parameters to refine performance:
SearchType: Switch between entity_connections (graph-heavy) or thematic_overview (summary-heavy).
ExtractionMode: Choose llm (creative) or gliner (fast/cost-effective).
Integrate this project as an MCP Server in Desktop Agents (Claude Desktop, Cursor, etc.) to give them memory of your documents.
Add to your MCP Config:
{
"mcpServers": {
"graphrag": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v",
"C:/Users/<USER>/.graphrag:/root/.graphrag",
"graphrag-query"
]
}
}
}graphrag list: Show all registered databases.
graphrag status <db>: Check entity/relationship counts and health.
graphrag delete <db> [--files]: Unregister database entry and optionally remove physical files.
graphrag index <db> [--reset]: Index documents into database (use --reset to skip duplicate checks).
To keep your project portable, move database files into a Managed/ folder inside your data directory.
Manual Move:
Move your_db.duckdb to [DOCUMENTS_HOME]/Managed/.
Re-register the path:
graphrag register my_db --db-path /app/documents/Managed/your_db.duckdbFor S3 management see S3_CHEATSHEET.md.
Traverse the knowledge graph starting from a specific entity. Returns the entity, its direct connections (other entities), and the relationships between them. Use this to build reasoning chains or verify facts about a known entity.
| Name | Required | Description | Default |
|---|---|---|---|
| entityName | Yes | Exact name of the entity to explore (e.g., 'Microsoft', 'Vistra') | |
| hops | No | How many relationship hops to traverse (default: 1, max: 3) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the return structure (entity, direct connections, relationships) and mentions traversal behavior with hops, but doesn't cover important aspects like rate limits, authentication requirements, error conditions, or what happens when the entity isn't found. The description adds value but leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that each earn their place. The first sentence states the core functionality, the second provides usage guidance. No wasted words, well-structured, and front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a graph traversal tool with no annotations and no output schema, the description provides adequate basic information about what the tool does and when to use it. However, it lacks details about the return format structure, error handling, performance characteristics, and limitations that would be important for an agent to use this tool effectively in complex scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents both parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema descriptions. It mentions traversal with hops but doesn't provide additional context about parameter usage or interactions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('traverse', 'returns') and resources ('knowledge graph', 'entity', 'direct connections', 'relationships'). It distinguishes from siblings by focusing on graph traversal from a specific entity rather than corpus statistics or general search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('to build reasoning chains or verify facts about a known entity'), which implicitly suggests it's for exploring known entities rather than discovering new ones. However, it doesn't explicitly state when NOT to use it or name specific alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get statistics about the indexed knowledge base. Returns counts of documents, chunks, entities, and relationships. Use for corpus health checks or to understand the scale of available data.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes what the tool returns (counts of documents, chunks, entities, relationships) but doesn't mention performance characteristics, potential limitations, or error conditions. The behavioral information is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two well-structured sentences. The first sentence states the purpose and return values, the second provides usage guidance. Every word earns its place with zero redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema, no annotations), the description provides adequate coverage of purpose and usage. However, without an output schema, it could benefit from more detail about the structure of returned statistics. The description is complete enough for basic understanding but leaves some implementation details unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters with 100% schema description coverage, so the baseline is 4. The description appropriately doesn't discuss parameters since none exist, focusing instead on the tool's purpose and output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Get statistics') and resources ('indexed knowledge base'), and it distinguishes from siblings by focusing on corpus-level metrics rather than entity exploration or search functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage contexts ('corpus health checks' and 'understand the scale of available data'), giving clear guidance on when to use this tool. However, it doesn't explicitly mention when NOT to use it or name specific alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the GraphRAG knowledge base with THREE distinct modes:
CRITICAL: For ticker symbols (ASTS, RKLB, NBIS) or acronyms, ALWAYS use 'keyword_lookup' FIRST. Semantic search (entity_connections/thematic_overview) can MISS exact ticker matches.
Workflow:
Ticker/Acronym Query → Use 'keyword_lookup' to find raw mentions
If found → Extract entity names from results
Then use 'entity_connections' or 'thematic_overview' with full entity names for deeper analysis
Mode Selection Guide:
'keyword_lookup': Direct BM25 retrieval for EXACT terms (tickers, acronyms, specific names) → Returns: Raw text chunks containing the literal search term → Use for: ASTS, NYSE:RKLB, "Direct-to-Cell", specific product names
'entity_connections': Find entities and their knowledge graph relationships → Returns: Entities + relationships + supporting chunks → Use for: Company relationships, competitive landscape, partnerships → Example: After finding 'AST SpaceMobile' via keyword_lookup, search 'AST SpaceMobile competitors partners'
'thematic_overview': High-level patterns and trends across corpus → Returns: Broad thematic context → Use for: Industry trends, macro narratives, sector analysis → Example: 'satellite telecommunications market trends'
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query string | |
| mode | No | **IMPORTANT**: Use 'keyword_lookup' for ticker symbols and acronyms. Use 'entity_connections' for relationships. Use 'thematic_overview' for broad patterns. Default: 'entity_connections' | |
| topK | No | Number of results (default: 10) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the critical workflow for ticker symbols, the risk of semantic search missing exact matches, and what each mode returns (e.g., raw text chunks for keyword_lookup). However, it lacks details on error handling, rate limits, or authentication needs, which are minor gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (critical note, workflow, mode selection guide), and every sentence adds value by explaining usage or behavior. It is appropriately sized for a complex tool with three modes, though it could be slightly more concise by reducing some repetition (e.g., the mode explanations are detailed but lengthy).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (three modes, no annotations, no output schema), the description is mostly complete. It covers purpose, usage, behavioral traits, and parameter semantics effectively. However, it lacks information on output format details (beyond high-level returns like 'raw text chunks') and potential limitations or errors, which would enhance completeness for a search tool without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds significant value by explaining the semantics of the 'mode' parameter in detail (e.g., keyword_lookup for exact terms, entity_connections for relationships), providing examples and use cases that go beyond the schema's enum descriptions. It clarifies the practical implications of mode selection, though it doesn't add much for 'query' or 'topK' beyond what the schema already covers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches a GraphRAG knowledge base with three distinct modes, specifying the exact functionality (searching with keyword_lookup, entity_connections, and thematic_overview). It distinguishes itself from siblings by focusing on search operations rather than exploration or statistics gathering, making the purpose specific and well-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each mode, including a critical workflow for ticker symbols/acronyms (use keyword_lookup first), and clear examples for each mode. It explicitly states alternatives within the tool itself (the three modes) and gives detailed when/when-not instructions, such as avoiding semantic search for exact ticker matches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0explore_entity_graphget_corpus_statssearchScored across 3 tools
Each tool has a clearly distinct purpose with no ambiguity: explore_entity_graph is for graph traversal from a specific entity, get_corpus_stats is for corpus-level statistics, and search is for querying the knowledge base with three distinct modes (keyword_lookup, entity_connections, thematic_overview). The tools do not overlap in functionality.
The tool names follow a consistent snake_case pattern (explore_entity_graph, get_corpus_stats, search), but 'search' is a generic verb compared to the more descriptive 'explore' and 'get', which is a minor deviation. Overall, the naming is predictable and readable.
With only 3 tools, the server feels thin for a GraphRAG system, as it might lack operations like updating or managing the knowledge base. However, the tools cover core query and exploration functions, making it borderline appropriate for basic usage.
The tool surface covers key operations for querying and exploring a GraphRAG knowledge base, including graph traversal, corpus statistics, and multi-mode search. Minor gaps exist, such as no tools for adding or modifying data, but agents can work around this for read-only analysis.
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
Persistent memory and knowledge graphs for AI agents. Hybrid search, context checkpoints, and more.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Company brain for AI agents — temporal knowledge graph search, exploration, and durable memory.
