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 Documentation: LightRAG GitHub
• API Documentation: LightRAG API Docs

Requirements

• LightRAG Server: Running instance of LightRAG (version 1.4.9+)
• Python: Version 3.10 or higher (for Python MCP)
• Node.js: Version 18.0.0 or higher (for TypeScript MCP)
• MCP Client: Compatible MCP client (Claude Desktop, Cline, etc.)

Architecture

The LightRAG MCP Server is built with:

• Python MCP: Using the MCP SDK for Python
• TypeScript MCP: Using the @modelcontextprotocol/sdk
• REST API Client: HTTP client for LightRAG server communication
• Error Handling: Comprehensive error handling and validation
• Type Safety: Full typing support in both implementations

Security Best Practices

1. Never commit API keys to version control
2. Use environment variables for sensitive credentials
3. Run LightRAG server on localhost or secure network
4. Enable authentication on LightRAG server for production
5. Monitor API usage through server logs

Troubleshooting

Error: Cannot connect to LightRAG server

Verify that:

1. Your LightRAG server is running (lightrag-server)
2. The server URL is correct (default: http://localhost:9621)
3. No firewall is blocking the connection

Error: Authentication failed

Verify that:

1. Your API key matches the LightRAG server configuration
2. Authentication is properly configured in both server and client
3. The API key is correctly set in environment variables

Error: Tool not found

Ensure you're using the correct tool name. All available tools are listed in the documentation above.

Error: Document upload failed

Check that:

1. The file path is correct and accessible
2. The file format is supported (PDF, TXT, DOCX, etc.)
3. You have sufficient permissions to read the file

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Documentation: GitHub README
• LightRAG Support: LightRAG GitHub
• Discord: LightRAG Discord Community

Acknowledgments

• Author: Lalit Suryan - Creator and maintainer
• Built with the Model Context Protocol SDK
• Powered by LightRAG
• Inspired by the MCP community

Changelog

Version 1.1.0 (Latest - December 2024)

Major Update - All Tools Verified Working

• ✅ 30 fully working tools with verified API endpoints
• ✅ Fixed authentication (X-API-Key header)
• ✅ Added critical file_source parameters
• ✅ Fixed request formats (doc_ids arrays, entity_name, etc.)
• ✅ Added new tools: query_data, reprocess_failed_documents, cancel_pipeline
• ✅ Added new graph tools: get_popular_labels, search_labels, create_entity, create_relation, merge_entities
• ✅ Fixed get_documents_paginated (POST method)
• ✅ Fixed get_knowledge_graph (wildcard label support)
• ✅ All endpoints match actual LightRAG API

Version 1.0.0 (Initial Release)

• Complete LightRAG API integration
• 30 management tools
• Support for all query modes
• Knowledge graph operations

Related Projects

• LightRAG - The core LightRAG library
• MiniRAG - RAG with small models
• VideoRAG - RAG for long-context videos
• RAG-Anything - All-in-One Multimodal RAG

Made with ❤️ by Lalit Suryan for the LightRAG and MCP communities