Document Management

insert_text

Add text content to LightRAG knowledge base.

interface InsertTextParams {
  text: string          // Text content to add
  file_source?: string  // Optional source identifier
}

Example:

{
  "tool": "insert_text",
  "arguments": {
    "text": "TypeScript is a typed superset of JavaScript",
    "file_source": "docs/typescript.md"
  }
}

insert_texts

Add multiple text documents at once.

interface InsertTextsParams {
  texts: string[]         // Array of text contents
  file_sources?: string[] // Optional source identifiers
}

scan_documents

Trigger scanning process for new documents in the input directory.

get_documents_paginated

Retrieve documents with pagination support.

interface GetDocumentsPaginatedParams {
  status_filter?: 'pending' | 'processing' | 'completed' | 'failed'
  page?: number           // Default: 1
  page_size?: number      // Default: 20
  sort_field?: string
  sort_direction?: 'asc' | 'desc'
}

get_document_status_counts

Get counts of documents by status.

get_track_status

Get the processing status of documents by tracking ID.

interface GetTrackStatusParams {
  track_id: string
}

delete_document

Delete documents by their IDs.

interface DeleteDocumentParams {
  doc_ids: string[]           // Document IDs to delete
  delete_file?: boolean       // Delete source files
  delete_llm_cache?: boolean  // Clear LLM cache
}

clear_documents

Clear all documents from the RAG system.

clear_cache

Clear all cache data from the LLM response cache storage.

reprocess_failed

Reprocess failed and pending documents.

Query Operations

query_text

Query the RAG system with various modes.

interface QueryTextParams {
  query: string
  mode?: 'local' | 'global' | 'hybrid' | 'naive' | 'mix' | 'bypass'
  top_k?: number
  enable_rerank?: boolean
  include_references?: boolean
}

Modes:

• local - Search within local context
• global - Global knowledge graph search
• hybrid - Combines local and global (default)
• naive - Simple vector search
• mix - Knowledge graph + vector search
• bypass - Direct LLM query without RAG

Example:

{
  "tool": "query_text",
  "arguments": {
    "query": "What is LightRAG?",
    "mode": "hybrid",
    "top_k": 5,
    "enable_rerank": true
  }
}

query_data

Advanced data retrieval endpoint for structured RAG analysis without LLM generation.

Graph Operations

get_graph_labels

Get all graph labels (entity types).

get_popular_labels

Get popular labels by node degree (most connected entities).

interface GetPopularLabelsParams {
  limit?: number  // Default: 10
}

search_labels

Search labels with fuzzy matching.

interface SearchLabelsParams {
  q: string       // Search query
  limit?: number  // Default: 10
}

Example:

{
  "tool": "search_labels",
  "arguments": {
    "q": "machine learning",
    "limit": 10
  }
}

get_knowledge_graph

Retrieve a connected subgraph of nodes.

interface GetKnowledgeGraphParams {
  label: string       // Starting entity label
  max_depth?: number  // Default: 2
  max_nodes?: number  // Default: 50
}

Example:

{
  "tool": "get_knowledge_graph",
  "arguments": {
    "label": "LightRAG",
    "max_depth": 2,
    "max_nodes": 50
  }
}

check_entity_exists

Check if an entity with the given name exists.

interface CheckEntityExistsParams {
  name: string
}

create_entity

Create a new entity in the knowledge graph.

interface CreateEntityParams {
  entity_name: string
  entity_data: {
    entity_type?: string
    description?: string
    source_id?: string
  }
}

update_entity

Update an entity's properties.

interface UpdateEntityParams {
  entity_name: string
  updated_data: object
  allow_rename?: boolean   // Allow renaming entity
  allow_merge?: boolean    // Allow merging with existing
}

delete_entity

Remove an entity and all its relationships.

interface DeleteEntityParams {
  entity_name: string
}

merge_entities

Merge multiple entities into a single entity, preserving all relationships.

interface MergeEntitiesParams {
  entities_to_change: string[]    // Entities to merge
  entity_to_change_into: string   // Target entity
}

Example:

{
  "tool": "merge_entities",
  "arguments": {
    "entities_to_change": ["ML", "machine learning"],
    "entity_to_change_into": "Machine Learning"
  }
}

create_relation

Create a new relationship between two entities.

interface CreateRelationParams {
  source_entity: string
  target_entity: string
  relation_data: {
    keywords?: string
    weight?: number
    description?: string
    source_id?: string
  }
}

update_relation

Update a relation's properties.

interface UpdateRelationParams {
  source_id: string
  target_id: string
  updated_data: object
}

delete_relation

Remove a relationship between two entities.

interface DeleteRelationParams {
  source_entity: string
  target_entity: string
}

System Management

get_pipeline_status

Get the current status of the document indexing pipeline.

cancel_pipeline

Request cancellation of the currently running pipeline.

Basic Workflow

Insert documents

{
  "tool": "insert_text",
  "arguments": {
    "text": "LightRAG is a simple and fast RAG system.",
    "file_source": "intro.txt"
  }
}

Wait for processing

{
  "tool": "get_pipeline_status"
}

Query your knowledge base

{
  "tool": "query_text",
  "arguments": {
    "query": "What is LightRAG?",
    "mode": "hybrid"
  }
}

Query Modes

Hybrid mode (default)

{
  "tool": "query_text",
  "arguments": {
    "query": "What is LightRAG?",
    "mode": "hybrid"
  }
}

Mix mode (knowledge graph + vector search)

{
  "tool": "query_text",
  "arguments": {
    "query": "Explain RAG systems",
    "mode": "mix"
  }
}

Graph Management

Search for entities

{
  "tool": "search_labels",
  "arguments": {
    "q": "machine learning",
    "limit": 10
  }
}

Get entity subgraph

{
  "tool": "get_knowledge_graph",
  "arguments": {
    "label": "LightRAG",
    "max_depth": 2,
    "max_nodes": 50
  }
}

Merge duplicate entities

{
  "tool": "merge_entities",
  "arguments": {
    "entities_to_change": ["ML", "machine learning"],
    "entity_to_change_into": "Machine Learning"
  }
}

Symptoms: Error: Use apiKey option or LIGHTRAG_API_KEY

Solution:

• Set LIGHTRAG_API_KEY in your .env file
• Pass via --token flag in CLI
• Provide in constructor options

# .env
LIGHTRAG_API_KEY=your-secret-key

Symptoms: Connection refused or ECONNREFUSED

Solution:

• Verify LightRAG server is running on port 9621
• Check LIGHTRAG_BASE_URL configuration
• Verify firewall settings
• Test connection: curl http://localhost:9621/health

Symptoms: Documents stuck in pending or processing state

Check pipeline status:

# Using CLI
curl http://localhost:9621/health

# Or use MCP tool
{
  "tool": "get_pipeline_status"
}

Common causes:

• LightRAG server overloaded
• Document format not supported
• Insufficient memory

Solutions:

• Check pipeline status: use get_pipeline_status tool
• Review LightRAG server logs
• Try reprocessing: use reprocess_failed tool
• Verify document format and size limits
• Increase server resources
• Split large documents

Symptoms: get_knowledge_graph returns no nodes

Solution:

• Verify entity exists: use check_entity_exists
• Try fuzzy search: use search_labels
• Check if documents are fully processed
• Increase max_depth and max_nodes parameters