Model Context Protocol (MCP) server for LightRAG - 30 fully working tools with complete RAG and Knowledge Graph integration
npm install @g99/lightrag-mcp-serverbash
npx @g99/lightrag-mcp-server
`
$3
`bash
npm install -g @g99/lightrag-mcp-server
`
$3
`bash
git clone https://github.com/lalitsuryan/lightragmcp.git
cd lightragmcp
npm install
`
Prerequisites
You need a running LightRAG server instance. Install and start LightRAG:
`bash
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
$3
Create a .env file or set the following environment variables:
`env
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
`
$3
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
$3
Add to your claude_desktop_config.json:
`json
{
"mcpServers": {
"lightrag": {
"command": "npx",
"args": ["@g99/lightrag-mcp-server"],
"env": {
"LIGHTRAG_SERVER_URL": "http://localhost:9621",
"LIGHTRAG_API_KEY": "your_api_key_here"
}
}
}
}
`
$3
Add to your MCP settings:
`json
{
"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
$3
#### insert_text
Insert a single text document into LightRAG.
Parameters:
- text (required): Text content to insert
- description (optional): Description of the text
Example:
`json
{
"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:
`json
{
"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:
`json
{
"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:
`json
{
"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:
`json
{}
`
#### get_documents
Retrieve all documents from LightRAG.
Parameters: None
Example:
`json
{}
`
#### 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:
`json
{
"page": 1,
"page_size": 20
}
`
#### delete_document
Delete a specific document by ID.
Parameters:
- document_id (required): ID of the document to delete
Example:
`json
{
"document_id": "doc_12345"
}
`
#### clear_documents
Clear all documents from LightRAG.
Parameters: None
Example:
`json
{}
`
#### document_status
Get processing status for documents.
Parameters:
- document_id (optional): Specific document ID to check
Example:
`json
{
"document_id": "doc_12345"
}
`
$3
#### 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:
`json
{
"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:
`json
{
"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:
`json
{
"query": "What is retrieval-augmented generation?",
"mode": "hybrid"
}
`
$3
#### get_knowledge_graph
Retrieve the complete knowledge graph from LightRAG.
Parameters: None
Example:
`json
{}
`
#### get_graph_structure
Get the structure and statistics of the knowledge graph.
Parameters: None
Example:
`json
{}
`
#### get_entities
Retrieve all entities from the knowledge graph.
Parameters:
- limit (optional): Maximum number of entities to retrieve
Example:
`json
{
"limit": 100
}
`
#### get_relations
Retrieve all relationships from the knowledge graph.
Parameters:
- limit (optional): Maximum number of relations to retrieve
Example:
`json
{
"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:
`json
{
"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:
`json
{
"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:
`json
{
"entity_id": "entity_789"
}
`
#### delete_relation
Delete a relationship from the knowledge graph.
Parameters:
- relation_id (required): ID of the relation to delete
Example:
`json
{
"relation_id": "rel_456"
}
`
$3
#### get_health
Check LightRAG server health and status.
Parameters: None
Example:
`json
{}
`
#### get_status
Get detailed system status and statistics.
Parameters: None
Example:
`json
{}
`
#### clear_cache
Clear LightRAG's internal cache.
Parameters:
- cache_type (optional): Type of cache to clear (default: "all")
Example:
`json
{
"cache_type": "llm"
}
`
#### get_config
Get current LightRAG server configuration.
Parameters: None
Example:
`json
{}
`
#### get_workspace_info
Get information about the current workspace.
Parameters: None
Example:
`json
{}
`
Usage Examples
$3
`typescript
// 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"
});
`
$3
`typescript
// 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"
});
`
$3
`typescript
// 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"
}
});
`
$3
`typescript
// 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
$3
- Python 3.10 or higher (for Python implementation)
- Node.js 18 or higher (for TypeScript implementation)
- Running LightRAG server instance
$3
`bash
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
`
$3
`bash
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
$3
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
$3
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
$3
Ensure you're using the correct tool name. All available tools are listed in the documentation above.
$3
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`)