LightRAG MCP Server

A comprehensive Model Context Protocol (MCP) server for LightRAG - Simple and Fast Retrieval-Augmented Generation. This server enables AI assistants to interact with LightRAG's powerful knowledge graph and RAG capabilities.

Overview

LightRAG MCP Server provides complete integration with LightRAG's API, offering 30 fully working tools for document management, knowledge graph operations, querying, and system management. Build sophisticated RAG applications with knowledge graph capabilities through a simple MCP interface.

Features

• Complete LightRAG API Coverage: Access all major LightRAG endpoints
• 30 Working Tools: All tools fully functional with correct API endpoints
• Knowledge Graph Operations: Full control over entities and relationships
• Multiple Query Modes: Support for naive, local, global, hybrid, and mix modes
• Document Management: Insert, upload, scan, and manage documents
• Streaming Support: Real-time streaming responses for queries
• Easy Installation: Install via npx

Installation

Quick Start (Recommended)

npx @g99/lightrag-mcp-server

Global Installation

npm install -g @g99/lightrag-mcp-server

From Source

git clone https://github.com/lalitsuryan/lightragmcp.git
cd lightragmcp
npm install

Prerequisites

You need a running LightRAG server instance. Install and start LightRAG:

# Install LightRAG
pip install "lightrag-hku[api]"

# Create .env file with your LLM and embedding configurations
cp env.example .env

# Start LightRAG server (default: http://localhost:9621)
lightrag-server

For detailed LightRAG server setup, visit LightRAG GitHub.

Configuration

Environment Variables

Create a .env file or set the following environment variables:

# Required: Your LightRAG server URL
LIGHTRAG_SERVER_URL=http://localhost:9621

# Optional: Authentication token if your LightRAG server requires it
LIGHTRAG_API_KEY=your_api_key_here

# Optional: Custom workspace name for data isolation
LIGHTRAG_WORKSPACE=default

Getting Your API Key

If your LightRAG server has authentication enabled:

1. Check your LightRAG server's .env file for LIGHTRAG_API_KEY
2. Alternatively, check the startup logs for the API key
3. Use that key in your MCP configuration

MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "lightrag": {
      "command": "npx",
      "args": ["@g99/lightrag-mcp-server"],
      "env": {
        "LIGHTRAG_SERVER_URL": "http://localhost:9621",
        "LIGHTRAG_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cline (VS Code Extension)

Add to your MCP settings:

{
  "mcpServers": {
    "lightrag": {
      "command": "npx",
      "args": ["@g99/lightrag-mcp-server"],
      "env": {
        "LIGHTRAG_SERVER_URL": "http://localhost:9621",
        "LIGHTRAG_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available Tools

Document Management Tools (10 tools)

insert_text

Insert a single text document into LightRAG.

Parameters:

• text (required): Text content to insert
• description (optional): Description of the text

Example:

{
  "text": "LightRAG is a powerful retrieval-augmented generation system that uses knowledge graphs.",
  "description": "Introduction to LightRAG"
}

insert_texts

Insert multiple text documents into LightRAG in batch.

Parameters:

• texts (required): Array of text documents with optional metadata

Example:

{
  "texts": [
    {
      "content": "LightRAG uses knowledge graphs for enhanced retrieval.",
      "title": "LightRAG Overview",
      "metadata": {"category": "documentation"}
    },
    {
      "content": "Knowledge graphs connect entities and relationships.",
      "title": "Knowledge Graphs"
    }
  ]
}

upload_document

Upload a document file to LightRAG.

Parameters:

• file_path (required): Path to the file to upload
• chunk_size (optional): Custom chunk size for document splitting
• chunk_overlap (optional): Overlap size between chunks

Example:

{
  "file_path": "/path/to/document.pdf",
  "chunk_size": 1200,
  "chunk_overlap": 100
}

upload_documents

Upload multiple documents in batch.

Parameters:

• file_paths (required): Array of file paths to upload

Example:

{
  "file_paths": [
    "/path/to/doc1.pdf",
    "/path/to/doc2.txt",
    "/path/to/doc3.docx"
  ]
}

scan_documents

Scan for new documents in the configured input directory.

Parameters: None

Example:

{}

get_documents

Retrieve all documents from LightRAG.

Parameters: None

Example:

{}

get_documents_paginated

Retrieve documents with pagination support.

Parameters:

• page (required): Page number (1-based)
• page_size (required): Number of documents per page (1-100)

Example:

{
  "page": 1,
  "page_size": 20
}

delete_document

Delete a specific document by ID.

Parameters:

• document_id (required): ID of the document to delete

Example:

{
  "document_id": "doc_12345"
}

clear_documents

Clear all documents from LightRAG.

Parameters: None

Example:

{}

document_status

Get processing status for documents.

Parameters:

• document_id (optional): Specific document ID to check

Example:

{
  "document_id": "doc_12345"
}

Query Tools (3 tools)

query_text

Query LightRAG with text using various retrieval modes.

Parameters:

• query (required): Query text
• mode (optional): Query mode - "naive", "local", "global", "hybrid", or "mix" (default: "hybrid")
• only_need_context (optional): Return only context without generation (default: false)
• top_k (optional): Number of top results to retrieve (default: 60)
• max_tokens (optional): Maximum tokens in response

Example:

{
  "query": "What are the main concepts in machine learning?",
  "mode": "hybrid",
  "top_k": 20
}

query_text_stream

Stream query results from LightRAG in real-time.

Parameters:

• query (required): Query text
• mode (optional): Query mode (default: "hybrid")
• only_need_context (optional): Return only context (default: false)

Example:

{
  "query": "Explain the evolution of artificial intelligence",
  "mode": "global"
}

query_with_citation

Query LightRAG and get results with source citations.

Parameters:

• query (required): Query text
• mode (optional): Query mode (default: "hybrid")

Example:

{
  "query": "What is retrieval-augmented generation?",
  "mode": "hybrid"
}

Knowledge Graph Tools (8 tools)

get_knowledge_graph

Retrieve the complete knowledge graph from LightRAG.

Parameters: None

Example:

{}

get_graph_structure

Get the structure and statistics of the knowledge graph.

Parameters: None

Example:

{}

get_entities

Retrieve all entities from the knowledge graph.

Parameters:

• limit (optional): Maximum number of entities to retrieve

Example:

{
  "limit": 100
}

get_relations

Retrieve all relationships from the knowledge graph.

Parameters:

• limit (optional): Maximum number of relations to retrieve

Example:

{
  "limit": 100
}

check_entity_exists

Check if an entity exists in the knowledge graph.

Parameters:

• entity_name (required): Name of the entity to check

Example:

{
  "entity_name": "Machine Learning"
}

update_entity

Update properties of an entity in the knowledge graph.

Parameters:

• entity_id (required): ID of the entity to update
• properties (required): Properties to update

Example:

{
  "entity_id": "entity_123",
  "properties": {
    "description": "Updated description",
    "category": "AI Technology"
  }
}

delete_entity

Delete an entity from the knowledge graph.

Parameters:

• entity_id (required): ID of the entity to delete

Example:

{
  "entity_id": "entity_789"
}

delete_relation

Delete a relationship from the knowledge graph.

Parameters:

• relation_id (required): ID of the relation to delete

Example:

{
  "relation_id": "rel_456"
}

System Management Tools (5 tools)

get_health

Check LightRAG server health and status.

Parameters: None

Example:

{}

get_status

Get detailed system status and statistics.

Parameters: None

Example:

{}

clear_cache

Clear LightRAG's internal cache.

Parameters:

• cache_type (optional): Type of cache to clear (default: "all")

Example:

{
  "cache_type": "llm"
}

get_config

Get current LightRAG server configuration.

Parameters: None

Example:

{}

get_workspace_info

Get information about the current workspace.

Parameters: None

Example:

{}

Usage Examples

Example 1: Index and Query Documents

// Insert documents
await use_mcp_tool("lightrag", "insert_texts", {
  texts: [
    {
      content: "LightRAG is an advanced RAG system with knowledge graph capabilities.",
      title: "LightRAG Introduction"
    },
    {
      content: "Knowledge graphs enhance retrieval by capturing entity relationships.",
      title: "Knowledge Graphs"
    }
  ]
});

// Query the indexed content
await use_mcp_tool("lightrag", "query_text", {
  query: "How does LightRAG use knowledge graphs?",
  mode: "hybrid"
});

Example 2: Upload and Process Documents

// Upload a PDF document
await use_mcp_tool("lightrag", "upload_document", {
  file_path: "/path/to/research-paper.pdf"
});

// Check document status
await use_mcp_tool("lightrag", "document_status", {
  document_id: "doc_12345"
});

// Query the document
await use_mcp_tool("lightrag", "query_text", {
  query: "What are the key findings in the research?",
  mode: "local"
});

Example 3: Work with Knowledge Graph

// Get knowledge graph structure
await use_mcp_tool("lightrag", "get_graph_structure", {});

// Check if entity exists
await use_mcp_tool("lightrag", "check_entity_exists", {
  entity_name: "Artificial Intelligence"
});

// Get all entities
await use_mcp_tool("lightrag", "get_entities", {
  limit: 50
});

// Update an entity
await use_mcp_tool("lightrag", "update_entity", {
  entity_id: "entity_123",
  properties: {
    description: "A comprehensive field of computer science",
    category: "Technology"
  }
});

Example 4: Advanced Query with Citation

// Query with source citations
await use_mcp_tool("lightrag", "query_with_citation", {
  query: "Explain the benefits of RAG systems",
  mode: "hybrid"
});

Query Modes Explained

LightRAG supports multiple query modes for different use cases:

• naive: Simple vector similarity search without knowledge graph
• local: Focus on local context and nearby entities
• global: Use global knowledge graph understanding
• hybrid: Combine local and global retrieval (recommended)
• mix: Advanced mode mixing knowledge graph and vector retrieval

Development

Prerequisites

• Python 3.10 or higher (for Python implementation)
• Node.js 18 or higher (for TypeScript implementation)
• Running LightRAG server instance

Setup for Development

# Clone the repository
git clone https://github.com/lalitsuryan/lightragmcp.git
cd lightragmcp

# For Python development
pip install -e ".[dev]"

# For TypeScript development
npm install
npm run build

Running Tests

# Python tests
pytest tests/

# TypeScript tests
npm test

API Reference

This MCP server implements the LightRAG API. For detailed API documentation, visit:

• Official Docum