LightRAG MCP Server

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

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

| 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: ```powershell

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