How do I use lightrag-fastmcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@lightrag-fastmcp query my knowledge base: what is the capital of France?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

lightrag-fastmcp

by leviethung2103

Overview Schema Source Related Servers Discussions Admin

Python

Remote

LightRAG FastMCP Bridge

This project exposes a FastMCP server that proxies to an existing LightRAG Server API.

Prerequisites

Before running this FastMCP bridge, you need to have a LightRAG server running. Follow the setup instructions below to install and configure the LightRAG server.

LightRAG Server Setup

Option 1: Quick Install with uv (Recommended)

# Install LightRAG Server as a tool
uv tool install "lightrag-hku[api]"

# Build front-end artifacts
cd lightrag_webui
bun install --frozen-lockfile
bun run build
cd ..

# Setup environment file
# Download env.example from https://github.com/HKUDS/LightRAG/blob/main/env.example
# or use the interactive setup wizard
cp env.example .env

# Edit .env with your LLM and embedding configurations
# At minimum, configure:
# - OPENAI_API_KEY or your preferred LLM provider
# - EMBEDDING_MODEL (e.g., BAAI/bge-m3)

# Launch the LightRAG server (default: http://localhost:9621)
lightrag-server

Option 2: Install from Source

# Clone the LightRAG repository
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG

# Bootstrap the development environment
make dev
source .venv/bin/activate  # Linux/macOS
# Or on Windows: .venv\Scripts\activate

# Setup environment file
make env-base  # Interactive setup wizard
# Or manually: cp env.example .env and edit it

# Launch the LightRAG server
lightrag-server

Option 3: Docker Compose

# Clone the LightRAG repository
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG

# Copy and configure environment file
cp env.example .env
# Edit .env with your LLM and embedding configurations

# Start with Docker Compose
docker compose up

Note: By default, the LightRAG server runs on http://localhost:9621. Make sure the server is accessible before running this FastMCP bridge.

For more detailed information about LightRAG configuration and options, visit the LightRAG repository.

Related MCP server: LightRAG MCP Server

Available Tools

This FastMCP bridge provides the following tools for interacting with your LightRAG server:

Health & Status

Tool	Description
`health()`	Check whether the LightRAG server is alive and responsive

Query Operations

Tool	Description
`query(question, include_references, include_chunk_content)`	Run a LightRAG query and return the final response payload
`query_stream(question, include_references, include_chunk_content)`	Run a streamed LightRAG query and concatenate the streamed text

Document Insertion

Tool	Description
`insert_text(text, file_source, title, metadata)`	Insert raw text into LightRAG knowledge base
`insert_texts(texts)`	Insert multiple text payloads into LightRAG in batch

Document Management

Tool	Description
`scan_documents()`	Trigger a document scan to process uploaded files
`document_status_counts()`	Get counts of documents by processing status
`list_documents(page, page_size, status)`	List paginated documents with optional status filtering
`delete_document(doc_id)`	Delete a document by its ID

Pipeline & Tracking

Tool	Description
`pipeline_state()`	Get the current ingestion pipeline state and progress
`get_track_status(track_id)`	Get detailed ingestion status for a specific track ID

Environment

LIGHTRAG_BASE_URL - LightRAG API base URL, for example http://localhost:9621
LIGHTRAG_API_KEY - optional bearer token used for /login-protected routes
MCP_TRANSPORT - stdio, sse, or streamable-http (default: streamable-http)
MCP_HOST - bind host for HTTP transports (default: 0.0.0.0)
MCP_PORT - bind port for HTTP transports (default: 3000)

Run

python -m lightrag_fastmcp_bridge.server

Docker

docker build -t lightrag-fastmcp .
docker run --rm -p 3000:3000 \
  -e LIGHTRAG_BASE_URL=http://host.docker.internal:9621 \
  lightrag-fastmcp

If you want SSE transport instead of streamable HTTP, set MCP_TRANSPORT=sse.

Configuration with Claude Code / Claude Desktop

This FastMCP server can be integrated with Claude Code (CLI), Claude Desktop, or other MCP-compatible clients.

Step 1: Start the FastMCP Server

First, ensure your LightRAG server is running, then start this FastMCP bridge:

# Set environment variables (optional, defaults shown)
export LIGHTRAG_BASE_URL=http://localhost:9621
export LIGHTRAG_API_KEY=your_api_key_if_needed
export MCP_HOST=0.0.0.0
export MCP_PORT=3000
export MCP_TRANSPORT=streamable-http  # or "sse" or "stdio"

# Start the server
python -m lightrag_fastmcp_bridge.server

The server will start on http://0.0.0.0:3000 (or your configured host/port).

Step 2: Configure Claude Code / Claude Desktop

Find Your Configuration File

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Add the MCP Server Configuration

Open the configuration file and add the following entry to the mcpServers section:

For streamable-http transport (default):

{
  "mcpServers": {
    "lightrag": {
      "transport": {
        "type": "streamable-http",
        "url": "http://localhost:3000/mcp"
      }
    }
  }
}

For SSE transport:

{
  "mcpServers": {
    "lightrag": {
      "transport": {
        "type": "sse",
        "url": "http://localhost:3000/sse"
      }
    }
  }
}

For stdio transport:

{
  "mcpServers": {
    "lightrag": {
      "command": "python",
      "args": [
        "-m",
        "lightrag_fastmcp_bridge.server"
      ],
      "env": {
        "LIGHTRAG_BASE_URL": "http://localhost:9621",
        "LIGHTRAG_API_KEY": "your_api_key_if_needed",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Step 3: Restart Claude Code / Claude Desktop

After saving the configuration file:

Quit Claude Code or Claude Desktop completely
Restart the application
The MCP server will be automatically connected on startup

Step 4: Verify the Connection

Once connected, you can verify the setup by asking Claude to use the LightRAG tools:

"Can you check if the LightRAG server is healthy?"
"What documents are in my LightRAG knowledge base?"

Claude should be able to use the health() and list_documents() tools to respond.

Usage Examples

Once configured, you can interact with your LightRAG knowledge base through Claude:

# Query your knowledge base
"Search for information about [topic] in my knowledge base"

# Insert new content
"Add this document to my knowledge base: [your text]"

# Check document status
"Show me the processing status of my documents"

# Delete documents
"Delete the document with ID [doc_id]"

Troubleshooting

Connection Issues:

Ensure the FastMCP server is running before starting Claude
Check that the port (3000) is not blocked by a firewall
Verify the LightRAG server (9621) is accessible

Configuration Errors:

Validate your JSON configuration syntax
Ensure environment variables are properly set
Check Claude's logs for MCP connection errors

Tool Not Available:

Restart Claude after configuration changes
Verify the MCP server is running
Check that the transport type matches your server configuration

Advanced Configuration

Custom Port:

{
  "mcpServers": {
    "lightrag": {
      "transport": {
        "type": "streamable-http",
        "url": "http://localhost:8000/mcp"
      }
    }
  }
}

Then start the server with:

export MCP_PORT=8000
python -m lightrag_fastmcp_bridge.server

With API Key:

{
  "mcpServers": {
    "lightrag": {
      "command": "python",
      "args": ["-m", "lightrag_fastmcp_bridge.server"],
      "env": {
        "LIGHTRAG_BASE_URL": "http://localhost:9621",
        "LIGHTRAG_API_KEY": "your-secure-api-key"
      }
    }
  }
}

For more information about MCP configuration, see the Model Context Protocol documentation.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

forkast-mcp-docs A
io.github.ForkastPredict
MCP server for querying Forkast documentation
Documentation Access Search Developer Tools
42
Backtest360 A
com.backtest360
MCP server exposing the Backtest360 engine API as tools for AI agents.
Finance Research & Data
202
mcp A
ai.llmse
Public MCP server for the LLM Search Engine
Search RAG Systems Developer Tools
102
docbaseOAuth
io.github.krayinc
DocBase MCP server for AI agents
Documentation Access Search Developer Tools
2

Related MCP Servers

my-mcp-server
Developer Tools
rhdh-exploration-org
F
license
Not graded
quality
D
maintenance
A FastMCP server that wraps a REST API as MCP tools, enabling AI agents to interact with the upstream API.
Updated 3 months ago (2026-06-10 21:20 UTC)
-
LightRAG MCP Server
RAG Systems Knowledge & Memory
a-earthperson
A
license
Not graded
quality
D
maintenance
MCP server for integrating LightRAG with AI tools. Provides a unified interface for interacting with LightRAG API through the MCP protocol.
Updated 7 months ago (2026-02-06 23:51 UTC)
1
MIT
R2R MCP Server
RAG Systems Knowledge & Memory Search
evgenygurin
A
license
Not graded
quality
D
maintenance
A FastMCP-based MCP server for the R2R API, enabling integration with document management, knowledge graphs, and RAG systems through automatically generated tools and resources.
Updated 10 months ago (2025-11-27 18:58 UTC)
MIT
lightrag-mcp
shemhamforash23
F
license
Not graded
quality
D
maintenance
MCP server that bridges LightRAG API with MCP-compatible clients, enabling retrieval-augmented generation, document management, and knowledge graph operations.
Updated 3 months ago (2026-06-08 18:50 UTC)
122
-