Index and Query Documents with Lucene

A Java-based MCP server that provides efficient document search and retrieval capabilities using Apache Lucene for full-text indexing and search, built on Spring Boot.

Installation

From Source

git clone https://github.com/your-username/mcp-lucene-server.git
cd mcp-lucene-server
mvn clean install
java -jar target/mcp-lucene-server-0.0.1-SNAPSHOT.jar

Docker

docker build -t mcp-lucene-server .
docker run -p 8080:8080 mcp-lucene-server

Spring Boot

mvn spring-boot:run

MCP Shim

cd mcp-shim
npm install
LUCENE_BASE_URL=http://localhost:8080/mcp/v1 npm start

Configuration

Claude Desktop

{
  "mcpServers": {
    "lucene": {
      "command": "/opt/homebrew/bin/node",
      "args": [".../MCP-Lucene-Server/mcp-shim/server.js"],
      "env": {
        "LUCENE_BASE_URL": "http://localhost:8080/mcp/v1",
        "MCP_FORCE_TEXT": "1"
      }
    }
  }
}

Claude Desktop with Wrapper Script

{
  "mcpServers": {
    "lucene": {
      "command": ".../MCP-Lucene-Server/mcp-shim/run-shim.sh",
      "env": {
        "LUCENE_BASE_URL": "http://localhost:8080/mcp/v1",
        "MCP_FORCE_TEXT": "1"
      }
    }
  }
}

Available Tools

Tool	Description
lucene_status	Get server/index status
lucene_upsert	Add or update documents
lucene_query	Query documents (with optional metadata filters)
lucene_delete	Delete by ID
lucene_list	List documents with pagination

Features

• MCP Compatibility: Implements the core Model Context Protocol
• Lucene-Based: Uses Apache Lucene for full-text search and indexing
• RESTful API: Provides a RESTful API for server interaction
• Document Management: Add, update, delete, and list documents in the Lucene index
• Complex Queries: Supports complex queries using Lucene query syntax
• Filtering: Filter queries based on document metadata
• Spring Boot: Built on Spring Boot for easy configuration and deployment
• Containerization: Includes instructions for containerizing the application using Docker

Environment Variables

Required

• LUCENE_BASE_URL - Base URL for the Lucene API server

Optional

• MCP_FORCE_TEXT - Force text output if the client cannot render JSON tool outputs

Usage Examples

Run lucene_status

Run lucene_list with: { "limit": 10, "offset": 0 }

Run lucene_upsert with: {"documents":[{"id":"doc-1","text":"hello world","metadata":{"lang":"en"}}]}

Run lucene_query with: {"queries":[{"query":"hello","top_k":5}]}

Run lucene_delete with: { "ids": ["doc-1"] }

Resources

• GitHub Repository

Notes

Requires Java 11+, Maven 3.6.0+, and optionally Docker. The server runs on port 8080 by default. Configuration can be customized using Spring Boot application properties, including server.port and lucene.index.path. The MCP shim enables integration with Claude Desktop via STDIO.