Index and Query Documents with Lucene

A Java-based MCP server providing document search and retrieval using Apache Lucene for full-text indexing and search, built on Spring Boot. It exposes an MCP-compatible tool interface backed by a RESTful API for document management: adding, updating, deleting, and listing documents in a Lucene index, plus complex Lucene query-syntax searches with metadata-based filtering.

Use it when an MCP client such as Claude Desktop needs full-text search and document indexing backed by Apache Lucene - upserting documents, running Lucene-syntax queries with metadata filters, or listing and deleting indexed documents. It is not a vector or embedding-based semantic search server - it is Lucene's classic full-text inverted-index search.

Five tools are exposed: 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), and lucene_list (list documents with pagination). The server supports complex queries using Lucene's query syntax and metadata-based filtering, is built on Spring Boot for straightforward setup and deployment, and includes Docker instructions for containerization. Configuration requires the LUCENE_BASE_URL environment variable (the Lucene server API base URL); MCP_FORCE_TEXT is optional, forcing text output when a client can't render JSON tool output. It requires Java 11+ and Maven 3.6.0+ (Docker optional), listens on port 8080 by default, and can be reconfigured via Spring Boot application properties such as server.port and lucene.index.path. A Node.js MCP shim bridges the Java server to Claude Desktop over STDIO. Besides building from source, the server can be run via Docker (docker build then docker run -p 8080:8080) or directly with mvn spring-boot:run; the shim itself is started separately with npm install followed by LUCENE_BASE_URL=http://localhost:8080/mcp/v1 npm start. Claude Desktop is pointed at the shim through an mcpServers config entry naming the Node executable and the shim's server.js path (or a wrapper shell script), with LUCENE_BASE_URL and MCP_FORCE_TEXT passed through its env block. Example tool invocations include running lucene_status with no arguments, lucene_list with a limit/offset pair, lucene_upsert with a documents array carrying id/text/metadata, lucene_query with a queries array specifying query and top_k, and lucene_delete with an ids array.

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

Developers who need MCP-connected full-text document search backed by Apache Lucene, integrated into Claude Desktop or another MCP client via a Node-based shim over STDIO.