Lightrag

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.

Features

• 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

Installation

# Clone the repository
git clone https://github.com/enriquecatala/mcp-lightrag.git
cd mcp-lightrag

# Install dependencies
uv sync

Quick Start

1. Start your LightRAG server (must be running before the MCP server)

2. Launch the MCP server:

   uv run mcp-lightrag --host localhost --port 9621
   

3. Connect your AI assistant via the MCP protocol (stdio transport)

Configuration

Option	Environment Variable	Default	Description
--host	LIGHTRAG_HOST	localhost	LightRAG API host
--port	LIGHTRAG_PORT	9621	LightRAG API port
--api-key	LIGHTRAG_API_KEY	(none)	Optional API key
--log-level	—	INFO	Logging verbosity

Setting up as MCP Server

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-lightrag with the actual full path to where you cloned this repository.

Smart Document Handling

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.

Available Tools

Search & Query

• query_knowledge_graph — Execute specialized RAG queries (mix, semantic, keyword, etc.) to answer questions based on your data.

Document Management

• 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.

Graph Operations

• 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).

System

• verify_server_health — Check if the LightRAG API is reachable and healthy.

Development

# Install dev dependencies
uv sync --all-extras

# Run tests
uv run python -m pytest

# Lint code
uv run ruff check src/

Publishing

To publish a new version to PyPI:

1. Update the version in pyproject.toml.
2. Build the package:

   uv run python -m build
   

3. Upload to PyPI (requires PyPI API token):

   uv run twine upload dist/*
   

Updating the Client

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 \
  --overwrite

This will update the client code in src/mcp_lightrag/client/light_rag_server_api_client based on the latest OpenAPI specification.

License

MIT