Optimized for Obsidian Vaults with smart upsert and document tracking capabilities, enabling agents to sync and reason over evolving Obsidian knowledge bases.
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., "@mcp-lightrag Search the knowledge graph for articles about artificial intelligence"
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.
A Model Context Protocol (MCP) server that enables AI assistants to interact with LightRAG knowledge graphs. Query documents, manage entities, and build semantic relationships through a standardized tool interface. Optimized for Obsidian Vaults: The built-in smart upsert and document tracking capabilities make it perfect for agents that need to sync and reason over evolving Obsidian knowledge bases.
Smart Updates: Intelligent upsert logic that detects changes in documents, skipping redundant uploads and re-indexing only when necessary
Knowledge Graph Queries: Perform semantic, keyword, or hybrid searches across your indexed documents
Document Ingestion: Add text, files, or entire directories to your knowledge base
Entity Management: Create, update, merge, and delete entities in the graph
Relationship Handling: Define and modify connections between entities
Robust Connectivity: Automatic retry with exponential backoff for reliable API communication
Flexible Configuration: Set options via environment variables or command-line arguments
Related MCP server: Obsidian MCP Server
# Clone the repository
git clone https://github.com/enriquecatala/mcp-lightrag.git
cd mcp-lightrag
# Install dependencies
uv syncStart your LightRAG server (must be running before the MCP server)
Launch the MCP server:
uv run mcp-lightrag --host localhost --port 9621Connect your AI assistant via the MCP protocol (stdio transport)
Option | Environment Variable | Default | Description |
|
|
| LightRAG API host |
|
|
| LightRAG API port |
|
| (none) | Optional API key |
| — |
| Logging verbosity |
To integrate this server with an MCP client (such as Claude Desktop), add the following configuration to your mcp-server-config.json key in your settings file. This configuration uses uv to run the server from the source directory.
{
"mcpServers": {
"mcp-lightrag": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/mcp-lightrag",
"run",
"mcp-lightrag",
"--host",
"localhost",
"--port",
"9621"
],
"env": {
"LIGHTRAG_API_KEY": "optional_api_key"
}
}
}
}Note: Replace
/absolute/path/to/mcp-lightragwith the actual full path to where you cloned this repository.
This server distinguishes itself with an intelligent Upsert Mechanism ideal for keeping in sync with Obsidian Vaults or other local knowledge bases:
New File → Uploads and indexes immediately.
Unchanged File → Detects identical content and skips (saving time and resources).
Modified File → Automatically removes the old version and indexes the new one. This allows agents to efficiently "watch" a folder and keep the RAG knowledge graph up-to-date without redundant processing.
query_knowledge_graph — Execute specialized RAG queries (mix, semantic, keyword, etc.) to answer questions based on your data.
ingest_text — Index raw text content directly into the graph.
ingest_file — Index a specific local file (absolute path required).
upload_and_index — Upload a file to the server for indexing (handles transfer).
ingest_batch — Recursively scan and index directories with pattern filtering.
upsert_document — Smart document upload: creates new, skips identical, or updates modified documents.
find_document — Search for a document by filename to check status and details.
get_latest_documents — Retrieve a paginated list of recently updated documents.
list_all_docs — List all documents in the system (warning: can be slow for large datasets).
check_indexing_status — Check if the background indexing pipeline is idle or busy.
create_entities — Manually insert new entities.
modify_entities — Update attributes of existing entities.
remove_entities — Delete specific entities.
unify_entities — Merge multiple entities into a single canonical entity.
connect_entities — Create or update relationships between entities.
purge_by_document — Delete a document and remove all its associated data from the graph.
get_graph_metadata — Explore the graph schema (available node labels and relationship types).
verify_server_health — Check if the LightRAG API is reachable and healthy.
# Install dev dependencies
uv sync --all-extras
# Run tests
uv run python -m pytest
# Lint code
uv run ruff check src/To publish a new version to PyPI:
Update the version in pyproject.toml.
Build the package:
uv run python -m buildUpload to PyPI (requires PyPI API token):
uv run twine upload dist/*If the LightRAG API evolves, you can regenerate the client using openapi-python-client. Ensure your LightRAG server is running (e.g., at http://localhost:9621), then run:
uv tool run openapi-python-client generate \
--url http://localhost:9621/openapi.json \
--output-path src/mcp_lightrag/client/light_rag_server_api_client \
--meta none \
--overwriteThis will update the client code in src/mcp_lightrag/client/light_rag_server_api_client based on the latest OpenAPI specification.
MIT
Check the current status of the document processing pipeline (idle or busy).
Inputs: no named parameters.
Define or update relationships between entities, including edge weights and descriptions.
Inputs: relations (required).
Manually insert specific entities into the knowledge graph.
Inputs: entities (required).
Check if a document exists by its filename or path. Returns a dictionary with detailed status: 'id', 'status' (processed/failed/pending), 'created_at', 'updated_at', 'content_length', 'chunks_count', and 'error_msg' if any.
Inputs: filename (required).
Retrieve schema information about the knowledge graph, including available node labels and relationship types.
Inputs: no named parameters.
Get a paginated list of the most recently updated documents. Useful for monitoring ingestion progress.
Inputs: limit, status.
Recursively index all files in a directory that match specific patterns.
Inputs: directory_path (required), recursive, max_depth, include_patterns, +1 more.
Index a specific local file from the file system. The file must be accessible by the running server.
Inputs: file_path (required).
Index raw text content directly into the knowledge graph. Useful for small snippets or dynamic data.
Inputs: content (required).
List ALL documents currently in the system. WARNING: Can be slow if there are many documents. Use get_latest_documents for better performance.
Inputs: no named parameters.
Update the properties (type, description, source_id) of existing entities.
Inputs: entities (required).
Remove all entities and relationships associated with specific document IDs from the graph.
Inputs: doc_ids (required).
Search the knowledge graph for information using various strategies. Ideal for answering questions based on indexed data.
Inputs: prompt (required), search_mode, limit, context_only, +1 more.
Delete one or more specific entities from the knowledge graph by name.
Inputs: names (required).
Merge multiple source entities into a single target entity to resolve duplicates or synonyms.
Inputs: sources (required), target (required), strategies.
Upload a file to the LightRAG server's input directory and trigger indexing. Handles file transfer if the server is remote.
Inputs: file_path (required).
Intelligently upload a document: if it doesn't exist, creates it; if it exists and is identical (same content length), skips upload; if it exists but was modified, deletes the old version and re-uploads.
Inputs: file_path (required).
Check if the LightRAG server is reachable and healthy.
Inputs: no named parameters.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 18 tools
Most tools have clearly distinct purposes, especially across document ingestion and entity management. However, some overlapping file-related tools (e.g., ingest_file vs upload_and_index) could cause slight confusion, and multiple document retrieval tools (find_document, get_latest_documents, list_all_docs) have overlapping but distinct use cases.
All tool names follow a consistent verb_noun pattern with underscore separators. The verbs are varied but appropriate for each action, and no mixed styles (e.g., camelCase) are present.
18 tools is a well-scoped number for a knowledge graph server. Each tool serves a specific function in document ingestion, entity management, querying, or monitoring, without unnecessary bloat.
The server covers document CRUD and entity management reasonably well, but lacks direct entity retrieval (only via query) and an explicit tool to delete a document record itself (only purge associated entities). These are notable gaps that may hinder agents in certain workflows.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Personal wiki and memory layer for AI assistants. Persistent, structured memory across sessions.
Persistent memory and knowledge graph for AI assistants — keyword + vector + graph search.