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

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.

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)

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

Document Management Tools (4–18)

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)

Utility Tools (29–30)

Transport Modes

HTTP + SSE (recommended for n8n)

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

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

1. 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

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