LightRAG MCP Server

Model Context Protocol (MCP) server for the LightRAG API — 30 tools covering queries, document management, knowledge graph operations, and server utilities.

---

Table of Contents

• Overview
• Prerequisites
• Quick Start
• Configuration
• All 30 Tools
• Transport Modes
• n8n Integration
• Docker Daemon
• Workspace Support
• Claude Desktop / Zed
• Development
• Troubleshooting

---

Overview

This MCP server acts as a bridge between any MCP-compatible AI client (n8n, Claude Desktop, Zed, Cursor, etc.) and a running LightRAG server.

AI Client (n8n / Claude Desktop / Zed)
        │
        │  MCP protocol (SSE or stdio)
        ▼
┌─────────────────────────┐
│  LightRAG MCP Server    │  ← this project
│  (Node.js + TypeScript) │
└─────────────────────────┘
        │
        │  HTTP REST
        ▼
┌────────────────────────┐
│  LightRAG API          │
│  http://localhost:9621 │
└────────────────────────┘

Key features:

• 30 tools covering all major LightRAG API endpoints
• Two transports: HTTP+SSE for n8n / remote clients, stdio for local desktop clients
• Workspace support: all tools accept an optional workspace parameter to target specific knowledge bases
• Docker daemon: runs as a background service, survives Ctrl+C and host reboots
• Graceful shutdown: handles SIGTERM/SIGINT properly so Docker can stop it cleanly

---

Prerequisites

Requirement	Version	Notes
Node.js	≥ 18	LTS recommended
npm	≥ 9	Comes with Node.js
LightRAG server	any	Must be running on localhost:9621 (or configured URL)
Docker (optional)	≥ 24	For daemon mode

LightRAG must already be running before you start the MCP server. If it's currently running from PowerShell on port 9621, that's perfect — no changes needed.

---

Quick Start

1. Install dependencies

# From the devstral-mcp directory
npm install

2. Build TypeScript

npm run build

3. Configure (optional)

# Copy the example config and edit if needed
Copy-Item .env.example .env
# Edit .env — most defaults work out of the box for a local LightRAG install

The only value you typically need to change is LIGHTRAG_BASE_URL if LightRAG is not on localhost:9621.

4. Start the server

# HTTP+SSE mode (for n8n) — default
npm run start:http

# stdio mode (for Claude Desktop / Zed)
npm run start:stdio

You should see:

┌──────────────────────────────────────────────────────┐
│         LightRAG MCP Server — Configuration          │
├──────────────────────────────────────────────────────┤
│  LightRAG URL  : http://localhost:9621               │
│  Transport     : http                                │
│  Listen        : 0.0.0.0:3000                        │
│  SSE endpoint  : http://localhost:3000/sse           │
└──────────────────────────────────────────────────────┘

5. Test connectivity

# Check the MCP server itself
Invoke-RestMethod http://localhost:3000/health

# Verify it can reach LightRAG
Invoke-RestMethod http://localhost:3000/

---

Configuration

All settings can be set in .env or as environment variables. Environment variables always take priority over .env.

Variable	Default	Description
LIGHTRAG_BASE_URL	http://localhost:9621	LightRAG server URL (no trailing slash)
LIGHTRAG_API_KEY	(empty)	API key for LightRAG. Leave empty if auth is disabled (default for local installs)
LIGHTRAG_TIMEOUT	30000	HTTP request timeout in milliseconds
LIGHTRAG_DEFAULT_WORKSPACE	(empty)	Default workspace. Empty = server default
MCP_TRANSPORT	http	Transport mode: http or stdio
MCP_HOST	0.0.0.0	Bind host for HTTP transport
MCP_PORT	3000	Port for HTTP+SSE transport
LOG_LEVEL	info	Log verbosity: error, warn, info, debug

The transport can also be set via CLI flag, which takes highest priority:

node dist/index.js --transport http
node dist/index.js --transport stdio

---

All 30 Tools

Query Tools (1–3)

#	Tool name	Description
1	lightrag_query	Query the knowledge base and get an LLM-generated answer. Supports all retrieval modes.
2	lightrag_query_stream	Same as above but uses the /query/stream endpoint (different server code path).
3	lightrag_query_data	Returns raw retrieval data (entities, relationships, chunks) without LLM generation.

Query modes (all query tools accept a mode parameter):

Mode	Description
mix	⭐ Recommended — combines knowledge graph with vector search
local	Focuses on specific entities and their direct relationships
global	Analyses broad relationship patterns across the whole graph
hybrid	Combines local + global strategies
naive	Plain vector similarity search, no knowledge graph
bypass	Direct LLM call, no retrieval at all

---

Document Management Tools (4–18)

#	Tool name	Description
4	lightrag_insert_text	Insert a single text string into the knowledge base
5	lightrag_insert_texts	Insert multiple texts in one request (batch)
6	lightrag_scan_documents	Trigger a scan of the server's input directory for new files
7	lightrag_list_documents	List all documents grouped by status (up to 1000)
8	lightrag_get_documents_paginated	Paginated document list with filtering and sorting
9	lightrag_get_document_status_counts	Quick count summary: PROCESSED / PENDING / FAILED / etc.
10	lightrag_get_track_status	Check indexing progress using a track_id
11	lightrag_delete_documents	Delete documents by ID (async, with optional file/cache deletion)
12	lightrag_delete_entity	Remove an entity node from the knowledge graph
13	lightrag_delete_relation	Remove a relationship edge from the knowledge graph
14	lightrag_clear_all_documents	⚠️ Wipe everything — all documents, entities, vectors
15	lightrag_get_pipeline_status	Monitor the document processing pipeline (busy/idle, progress)
16	lightrag_cancel_pipeline	Request graceful cancellation of the running pipeline
17	lightrag_reprocess_failed	Retry documents stuck in FAILED or PENDING state
18	lightrag_clear_cache	Clear LLM response cache (forces fresh extraction on next insert)

Typical insert workflow:

lightrag_insert_text → returns track_id
lightrag_get_track_status(track_id) → poll until PROCESSED
lightrag_query → ask questions

---

Graph / Entity / Relation Tools (19–28)

#	Tool name	Description
19	lightrag_get_graph_labels	List all entity names in the knowledge graph
20	lightrag_get_popular_labels	Get the most-connected entities (sorted by degree)
21	lightrag_search_labels	Fuzzy search for entity names
22	lightrag_get_knowledge_graph	Get a subgraph around a specific entity (nodes + edges)
23	lightrag_check_entity_exists	Check if an entity with a given name exists
24	lightrag_create_entity	Manually create a new entity node
25	lightrag_edit_entity	Update entity properties, rename, or merge with another entity
26	lightrag_create_relation	Create a relationship between two existing entities
27	lightrag_edit_relation	Update relationship properties
28	lightrag_merge_entities	Consolidate duplicate entities, transferring all relationships

---

Utility Tools (29–30)

#	Tool name	Description
29	lightrag_health_check	Full server health: version, LLM config, storage backends, pipeline state
30	lightrag_get_auth_status	Authentication configuration status

---

Transport Modes

HTTP + SSE (recommended for n8n)

The default mode. Starts an Express server with two endpoints:

Endpoint	Method	Purpose
/sse	GET	MCP client connects here to open an SSE session
/messages	POST	MCP client sends tool call requests
/health	GET	Liveness check (no auth required)
/	GET	Server info

npm run start:http
# or
npm start  # same thing

stdio (for Claude Desktop, Zed, Cursor)

Used when the MCP client spawns this process as a child and communicates via stdin/stdout.

npm run start:stdio

---

n8n Integration

Step 1: Start the MCP server

npm run start:http
# MCP server now listening at http://localhost:3000/sse

Or via Docker (see Docker Daemon section).

Step 2: Create MCP Client credential in n8n

1. Open n8n → Settings → Credentials → New Credential
2. Search for MCP Client API
3. Set SSE URL to:
   • Local: http://localhost:3000/sse
   • Docker (same compose network): http://lightrag-mcp:3000/sse
   • Docker (host machine): http://host.docker.internal:3000/sse
4. Save the credential

Step 3: Import the workflow template

1. In n8n, go to Workflows → Import from file
2. Select n8n/lightrag-workflow.json from this project
3. Open the imported workflow
4. Update the OpenAI GPT-4o-mini node with your OpenAI credential
5. Update the LightRAG MCP Tools node with the MCP credential you just created
6. Click Save and Activate

Step 4: Test

Open the chat in n8n and try:

• "Is LightRAG running?" → triggers lightrag_health_check
• "What documents do you know about?" → triggers lightrag_get_document_status_counts
• "Tell me about [topic]" → triggers lightrag_query

Network configuration

Scenario	LIGHTRAG_BASE_URL	n8n MCP SSE URL
Everything on host machine	http://localhost:9621	http://localhost:3000/sse
MCP in Docker, LightRAG on host	http://host.docker.internal:9621	http://localhost:3000/sse
Everything in Docker (same network)	http://lightrag:9621	http://lightrag-mcp:3000/sse

---

Docker Daemon

Running the MCP server in Docker keeps it alive even after closing the terminal window. It will restart automatically after crashes or host reboots.

Build and start

# From the devstral-mcp directory
docker compose -f docker/docker-compose.yml up -d --build

Common commands

# Check status
docker compose -f docker/docker-compose.yml ps

# Follow logs
docker compose -f docker/docker-compose.yml logs -f

# Stop the daemon (Ctrl+C does NOT stop it — this does)
docker compose -f docker/docker-compose.yml down

# Restart without rebuilding
docker compose -f docker/docker-compose.yml restart

# Rebuild after code changes
docker compose -f docker/docker-compose.yml up -d --build

Why it survives Ctrl+C

• restart: unless-stopped — Docker automatically restarts the container if it exits for any reason
• init: true — Uses tini as PID 1 so Node.js receives SIGTERM properly
• stop_grace_period: 15s — Docker waits 15 seconds for graceful shutdown before force-killing
• The Node.js process handles SIGTERM/SIGINT gracefully, closing SSE sessions and the HTTP server

Environment variables for Docker

Create a .env file next to docker/docker-compose.yml (or in the project root):

# If LightRAG runs on the host machine (not in Docker)
LIGHTRAG_BASE_URL=http://host.docker.internal:9621

# If LightRAG runs in Docker on the same network
# LIGHTRAG_BASE_URL=http://lightrag:9621

MCP_PORT=3000
LOG_LEVEL=info

---

Workspace Support

LightRAG supports multiple isolated knowledge bases called workspaces. All 30 tools accept an optional workspace parameter.

How it works:

• When workspace is provided in a tool call, the MCP server sends it as the LIGHTRAG-WORKSPACE HTTP header to LightRAG
• LightRAG routes the request to the workspace-specific storage
• Workspace names must contain only letters, digits, and underscores ([a-zA-Z0-9_]+)

Example use cases:

• workspace: "python_books" — knowledge base with Python programming books
• workspace: "company_docs" — internal company documentation
• workspace: "research_papers" — academic papers collection

Set a default workspace so you don't have to pass it every time:

# .env
LIGHTRAG_DEFAULT_WORKSPACE=python_books

Individual tool calls can still override the default by passing a different workspace value.

---

Claude Desktop / Zed

To use this MCP server with Claude Desktop or Zed, use stdio transport.

Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "lightrag": {
      "command": "node",
      "args": ["C:/path/to/devstral-mcp/dist/index.js", "--transport", "stdio"],
      "env": {
        "LIGHTRAG_BASE_URL": "http://localhost:9621",
        "LIGHTRAG_DEFAULT_WORKSPACE": ""
      }
    }
  }
}

Zed

Add to Zed settings.json:

{
  "context_servers": {
    "lightrag-mcp": {
      "command": {
        "path": "node",
        "args": ["C:/path/to/devstral-mcp/dist/index.js", "--transport", "stdio"],
        "env": {
          "LIGHTRAG_BASE_URL": "http://localhost:9621"
        }
      }
    }
  }
}

Replace C:/path/to/devstral-mcp with the actual absolute path to this project.

---

Development

# Install dependencies
npm install

# Run in development mode with hot reload (HTTP transport)
npm run dev:http

# Run in development mode (stdio transport)
npm run dev:stdio

# Type-check without building
npm run typecheck

# Build for production
npm run build

# Clean build output
npm run clean

Project structure

devstral-mcp/
├── src/
│   ├── index.ts           # Entry point — transport selection and startup
│   ├── server.ts          # McpServer factory — registers all 30 tools
│   ├── config.ts          # Typed environment configuration + logger
│   ├── client.ts          # Axios HTTP client for LightRAG API
│   └── tools/
│       ├── query.ts       # Tools 1–3: query, query_stream, query_data
│       ├── documents.ts   # Tools 4–18: insert, scan, list, delete, pipeline
│       └── graph.ts       # Tools 19–30: entities, relations, labels, health
├── docker/
│   ├── Dockerfile         # Multi-stage production build
│   └── docker-compose.yml # Daemon with restart:unless-stopped
├── n8n/
│   └── lightrag-workflow.json  # n8n AI Agent workflow template
├── .env.example           # All configurable environment variables
├── package.json
├── tsconfig.json
└── README.md

---

Troubleshooting

"Cannot connect to LightRAG at http://localhost:9621"

The LightRAG server is not reachable. Check:

# Is LightRAG running?
Invoke-RestMethod http://localhost:9621/health

# Is the URL correct in .env?
Get-Content .env | Select-String LIGHTRAG_BASE_URL

If LightRAG is running in Docker and the MCP server is on the host:

LIGHTRAG_BASE_URL=http://localhost:9621   # ✅ correct (Docker maps the port)

If both are in Docker containers on different compose files:

LIGHTRAG_BASE_URL=http://host.docker.internal:9621   # ✅ correct

n8n cannot connect to the MCP server

1. Verify the MCP server is running: Invoke-RestMethod http://localhost:3000/health
2. Check the SSE URL in your n8n MCP credential
3. If n8n is in Docker and MCP server is on the host, use http://host.docker.internal:3000/sse
4. If both are in Docker on the same network, use http://lightrag-mcp:3000/sse

Tools return "Request timed out"

LightRAG operations (especially document insertion with LLM extraction) can take several minutes.

# .env — increase timeout to 5 minutes
LIGHTRAG_TIMEOUT=300000

Documents stuck in PENDING or PROCESSING

# Use lightrag_get_pipeline_status to see what's happening
# Then try lightrag_reprocess_failed to retry stuck documents

"Session not found" on POST /messages

The SSE session expired. The MCP client needs to reconnect to /sse first. This is handled automatically by most MCP clients.

TypeScript build errors

# Clean and rebuild
npm run clean
npm run build

# Check for type errors
npm run typecheck

---

License

MIT