Daniel LightRAG MCP Server

A comprehensive MCP (Model Context Protocol) server that provides 100% functional integration with LightRAG API, offering 22 fully working tools across 4 categories for complete document management, querying, knowledge graph operations, and system management.

🎉 Status: 100% Functional

All 22 tools are working perfectly after comprehensive testing and optimization:

✅ Document Management: 6/6 tools working (100%)
✅ Query Operations: 2/2 tools working (100%)
✅ Knowledge Graph: 6/6 tools working (100%)
✅ System Management: 4/4 tools working (100%)
✅ Health Check: 1/1 tools working (100%)

Features

Document Management: 6 tools for inserting, uploading, scanning, retrieving, and managing documents
Query Operations: 2 tools for text queries with regular and streaming responses
Knowledge Graph: 6 tools for accessing, checking, updating, and managing entities and relations
System Management: 4 tools for health checks, status monitoring, and cache management
Comprehensive Error Handling: Robust error handling with detailed error messages
Full API Coverage: Complete integration with LightRAG API 0.1.96+

Quick Start

Install the server:
pip install -e .
Start LightRAG server (ensure it's running on http://localhost:9621)
Configure your MCP client (e.g., Claude Desktop):
{ "mcpServers": { "daniel-lightrag": { "command": "python", "args": ["-m", "daniel_lightrag_mcp"] } } }
Test the connection: Use the get_health tool to verify everything is working.

Installation

# Basic installation
pip install -e .

# With development dependencies
pip install -e ".[dev]"

Usage

Command Line

Start the MCP server:

daniel-lightrag-mcp

Environment Variables

Configure the server with environment variables:

export LIGHTRAG_BASE_URL="http://localhost:9621"
export LIGHTRAG_API_KEY="your-api-key"  # Optional
export LIGHTRAG_TIMEOUT="30"            # Optional
export LOG_LEVEL="INFO"                 # Optional

daniel-lightrag-mcp

Configuration

The server expects LightRAG to be running on http://localhost:9621 by default. Make sure your LightRAG server is started before running this MCP server.

MCP Client Configuration

Add to your MCP client (e.g., Claude Desktop):

{
  "mcpServers": {
    "daniel-lightrag": {
      "command": "python",
      "args": ["-m", "daniel_lightrag_mcp"],
      "env": {
        "LIGHTRAG_BASE_URL": "http://localhost:9621",
        "LIGHTRAG_API_KEY": "lightragsecretkey"
      }
    }
  }
}

For detailed configuration options, see MCP_CONFIGURATION_GUIDE.md.

Implementation Details

This server has undergone comprehensive testing and optimization to achieve 100% functionality. Key improvements include:

HTTP Client Fixes: Proper DELETE request handling with JSON bodies
Request Parameter Validation: All request models aligned with LightRAG API
Response Model Alignment: All response models match actual server responses
File Source Implementation: Critical fix preventing database corruption
Knowledge Graph Access: Optimized label parameters for full graph access

For complete technical details, see IMPLEMENTATION_GUIDE.md.

Available Tools (22 Total - All Working ✅)

Document Management Tools (6 tools)

`insert_text`

Insert text content into LightRAG.

Parameters:

text (required): Text content to insert

Example:

{
  "text": "This is important information about machine learning algorithms and their applications in modern AI systems."
}

`insert_texts`

Insert multiple text documents into LightRAG.

Parameters:

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

Example:

{
  "texts": [
    {
      "title": "AI Overview",
      "content": "Artificial Intelligence is transforming industries...",
      "metadata": {"category": "technology", "author": "researcher"}
    },
    {
      "content": "Machine learning algorithms require large datasets..."
    }
  ]
}

`upload_document`

Upload a document file to LightRAG.

Parameters:

file_path (required): Path to the file to upload

Example:

{
  "file_path": "/path/to/document.pdf"
}

`scan_documents`

Scan for new documents in LightRAG.

Parameters: None

Example:

{}

`get_documents`

Retrieve all documents from LightRAG.

Parameters: None

Example:

{}

`get_documents_paginated`

Retrieve documents with pagination.

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:

{}

Query Tools (2 tools)

`query_text`

Query LightRAG with text.

Parameters:

query (required): Query text
mode (optional): Query mode - "naive", "local", "global", or "hybrid" (default: "hybrid")
only_need_context (optional): Whether to only return context without generation (default: false)

Example:

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

`query_text_stream`

Stream query results from LightRAG.

Parameters:

query (required): Query text
mode (optional): Query mode - "naive", "local", "global", or "hybrid" (default: "hybrid")
only_need_context (optional): Whether to only return context without generation (default: false)

Example:

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

Knowledge Graph Tools (6 tools)

`get_knowledge_graph`

Retrieve the knowledge graph from LightRAG.

Parameters: None

Example:

{}

`get_graph_labels`

Get labels from the knowledge graph.

Parameters: None

Example:

{}

`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 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 for machine learning",
    "category": "AI Technology"
  }
}

`update_relation`

Update a relation in the knowledge graph.

Parameters:

relation_id (required): ID of the relation to update
properties (required): Properties to update

Example:

{
  "relation_id": "rel_456",
  "properties": {
    "strength": 0.9,
    "type": "implements"
  }
}

`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 relation from the knowledge graph.

Parameters:

relation_id (required): ID of the relation to delete

Example:

{
  "relation_id": "rel_101"
}

System Management Tools (4 tools)

`get_pipeline_status`

Get the pipeline status from LightRAG.

Parameters: None

Example:

{}

`get_track_status`

Get track status by ID.

Parameters:

track_id (required): ID of the track to get status for

Example:

{
  "track_id": "track_abc123"
}

`get_document_status_counts`

Get document status counts.

Parameters: None

Example:

{}

`clear_cache`

Clear LightRAG cache.

Parameters: None

Example:

{}

`get_health`

Check LightRAG server health.

Parameters: None

Example:

{}

Example Workflows

Complete Document Management Workflow

Check server health:
{"tool": "get_health", "arguments": {}}
Insert documents:
{ "tool": "insert_texts", "arguments": { "texts": [ { "title": "AI Research Paper", "content": "Recent advances in transformer architectures have shown remarkable improvements in natural language understanding tasks...", "metadata": {"category": "research", "year": 2024} } ] } }
Query the knowledge base:
{ "tool": "query_text", "arguments": { "query": "What are the recent advances in transformer architectures?", "mode": "hybrid" } }
Explore the knowledge graph:
{"tool": "get_knowledge_graph", "arguments": {}}
Check entity existence:
{ "tool": "check_entity_exists", "arguments": {"entity_name": "transformer architectures"} }

Knowledge Graph Management Workflow

Get current graph structure:
{"tool": "get_knowledge_graph", "arguments": {}}
Get available labels:
{"tool": "get_graph_labels", "arguments": {}}
Update entity properties:
{ "tool": "update_entity", "arguments": { "entity_id": "transformer_arch_001", "properties": { "description": "Advanced neural network architecture for sequence processing", "applications": ["NLP", "computer vision", "speech recognition"], "year_introduced": 2017 } } }
Update relation properties:
{ "tool": "update_relation", "arguments": { "relation_id": "rel_improves_002", "properties": { "improvement_factor": 2.5, "confidence": 0.92, "evidence": "Multiple benchmark studies" } } }

System Monitoring Workflow

Check overall health:
{"tool": "get_health", "arguments": {}}
Monitor pipeline status:
{"tool": "get_pipeline_status", "arguments": {}}
Check document processing status:
{"tool": "get_document_status_counts", "arguments": {}}
Track specific operations:
{ "tool": "get_track_status", "arguments": {"track_id": "upload_batch_001"} }
Clear cache when needed:
{"tool": "clear_cache", "arguments": {}}

Error Handling

The server provides comprehensive error handling with detailed error messages:

Connection Errors: When LightRAG server is unreachable
Authentication Errors: When API key is invalid or missing
Validation Errors: When input parameters are invalid
API Errors: When LightRAG API returns errors
Timeout Errors: When requests exceed timeout limits
Server Errors: When LightRAG server returns 5xx status codes

All errors include:

Error type and message
HTTP status code (when applicable)
Timestamp
Tool name that caused the error
Additional context data when available

Error Response Format

{
  "tool": "insert_text",
  "error_type": "LightRAGConnectionError",
  "message": "Failed to connect to LightRAG server at http://localhost:9621",
  "timestamp": 1703123456.789,
  "status_code": null,
  "response_data": {}
}

Common Error Scenarios

Connection Errors

{
  "error_type": "LightRAGConnectionError",
  "message": "Connection refused to http://localhost:9621",
  "status_code": null
}

Validation Errors

{
  "error_type": "LightRAGValidationError", 
  "message": "Missing required arguments for query_text: ['query']",
  "validation_errors": [
    {
      "loc": ["query"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

API Errors

{
  "error_type": "LightRAGAPIError",
  "message": "Document not found",
  "status_code": 404,
  "response_data": {
    "detail": "Document with ID 'doc_123' does not exist"
  }
}

Troubleshooting

Quick Diagnostics

Check LightRAG Server Status:
curl http://localhost:9621/health
Test MCP Server:
python -m daniel_lightrag_mcp & sleep 2 pkill -f daniel_lightrag_mcp
Verify Installation:
python -c "import daniel_lightrag_mcp; print('OK')"

Common Issues

Server Won't Start

Check Python version: Requires Python 3.8+
Verify dependencies: Run pip install -e .
Check port availability: Ensure no conflicts on stdio

Connection Refused

LightRAG not running: Start LightRAG server first
Wrong URL: Verify LIGHTRAG_BASE_URL environment variable
Firewall blocking: Check firewall settings for port 9621

Authentication Failed

Missing API key: Set LIGHTRAG_API_KEY environment variable
Invalid key: Verify API key with LightRAG server
Key format: Ensure key format matches LightRAG expectations

Timeout Errors

Increase timeout: Set LIGHTRAG_TIMEOUT=60 environment variable
Check server load: Verify LightRAG server performance
Network latency: Test direct API calls with curl

Tool Not Found

Restart MCP client: Reload server configuration
Check tool name: Verify exact tool name spelling
Server registration: Ensure all 22 tools are listed

Debug Mode

Enable detailed logging:

export LOG_LEVEL=DEBUG
python -m daniel_lightrag_mcp

Getting Help

Check server logs for detailed error messages
Test individual tools with minimal examples
Verify LightRAG server is responding correctly
Review the Configuration Guide for setup details

Development

Install development dependencies:

pip install -e ".[dev]"

Run tests:

pytest

Run tests with coverage:

pytest --cov=src/daniel_lightrag_mcp --cov-report=html

Format code:

black src/ tests/
isort src/ tests/

License

MIT License

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A comprehensive MCP server that provides full integration with LightRAG API, offering 22 tools across document management, querying, knowledge graph operations, and system management.

Related MCP Servers

MCP Documentation Server
esakrissa
-
security
F
license
-
quality
A customized MCP server that enables integration between LLM applications and documentation sources, providing AI-assisted access to LangGraph and Model Context Protocol documentation.
Last updated -
1
RAG Memory MCP
ttommyth
-
security
F
license
-
quality
An advanced MCP server providing RAG-enabled memory through a knowledge graph with vector search capabilities, enabling intelligent information storage, semantic retrieval, and document processing.
Last updated -
41
26
MCP AI Service Platform
dkb12138ggg
-
security
A
license
-
quality
A powerful AI service platform that provides complete MCP tool calling capabilities and RAG knowledge base functionality, enabling users to connect to multiple MCP servers and perform intelligent document search.
Last updated -
Apache 2.0
RAG Anything MCP Server
jesse-merhi
-
security
A
license
-
quality
An MCP server that provides comprehensive multimodal Retrieval-Augmented Generation (RAG) capabilities for processing and querying document directories, supporting text, images, tables, and equations.
Last updated -
5
MIT License

View all related MCP servers