simpleSearchLABSCO SUMMARY
A big tool surface with a switch to make it small.
LUCENE_TOOLS_INCLUDE and LUCENE_TOOLS_EXCLUDE take group names — search, semantic, debug, info, observability, crawler, admin — so a small model can be given just the two search tools, and exclude always wins over include. If you want everything except the destructive maintenance, set LUCENE_TOOLS_EXCLUDE to purgeIndex,unlockIndex.
What it is
A Lucene full-text server with a document crawler attached. It walks the directories you nominate, extracts text and metadata from PDFs, Microsoft Office and OpenOffice files, and keeps the index current — incrementally, skipping unchanged files and removing orphans.
What you get
simpleSearchtakes plain text with no Lucene syntax and treats special characters as literals;extendedSearchaccepts the full query language with booleans, wildcards and proximitysemanticSearchfinds related documents with no shared keywords, andprofileSemanticSearchshows the cosine scores and matched chunks so you can tune the thresholdprofileQueryexplains a result set: which terms carried the score, how each filter cut the candidate pool, and where the query can be improved- Crawler control from the chat:
startCrawl,pauseCrawler,resumeCrawler,getCrawlerStats,getCrawlerStatus, andlistCrawlableDirectories,addCrawlableDirectory,removeCrawlableDirectoryto change what is indexed at runtime getIndexStats,listIndexedFieldsandgetDocumentDetails— the last reads a document straight out of the index even if the original file has movedsuggestTermsandgetTopTermsexpose the actual vocabulary of your corpus, which is how you find the author or file-type value to filter on- Maintenance tools
optimizeIndex,purgeIndex,unlockIndex,getIndexAdminStatus, andindexAdmin, which renders a small UI inline in the client
Requirements
Java 25 or later. Run the built JAR over stdio with -Dspring.profiles.active=deployed, which is what keeps console logging out of the protocol stream. The Docker image mirkosertic42/mcpluceneserver:main is HTTP-only and listens on port 9000. Semantic search needs VECTOR_MODEL set to e5-base or e5-large, and JAVA_OPTS raised from its default of -Xmx2g. Crawl configuration persists to ~/.mcplucene/config.yaml.
Setup effort
Build from source
USE CASES
01
Finding a document you know exists somewhere
Search in plain language, filter by author, language or file type, and read the matching passages without opening the file.
02
Getting a search to return what you meant
Profile the query to see which filter removed the documents you expected and which terms actually scored.
03
Adding a new folder to the corpus mid-conversation
Name the directory and start the crawl from the chat; the change is written to the config file and survives a restart.
04
Working out what vocabulary the index actually has
List the most frequent terms in a field before writing a filter, instead of guessing the spelling of an author or a language code.
23 tools
Listed in project docs. Your client may show a different list.
extendedSearchsemanticSearchprofileSemanticSearchprofileQuerygetIndexStatslistIndexedFieldsgetDocumentDetailssuggestTermsgetTopTermsstartCrawlgetCrawlerStatsgetCrawlerStatuspauseCrawlerresumeCrawlerlistCrawlableDirectoriesaddCrawlableDirectoryremoveCrawlableDirectoryoptimizeIndexpurgeIndexunlockIndexgetIndexAdminStatusindexAdminBEFORE YOU INSTALL
What to know first
Tools you get
23 tools named in the project's documentation.
Requires
- Java 25 or later
- Maven 3.9+ (only if building from source)
INSTALLATION
Connect your client
MCP Clients
Claude Desktop
Download the latest build from the project's GitHub Actions artifacts or its Releases page (https://github.com/mirkosertic/MCPLuceneServer/releases) and extract it, or build it from source — the build writes target/luceneserver-0.0.1-SNAPSHOT.jar:
Get the JAR
CLAUDE DESKTOP · TERMINAL
git clone https://github.com/mirkosertic/MCPLuceneServer
cd MCPLuceneServer
./mvnw clean package -DskipTestsAdd it to claude_desktop_config.json
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"lucene-search": {
"command": "java",
"args": [
"--enable-native-access=ALL-UNNAMED",
"-Xmx2g",
"-Dspring.profiles.active=deployed",
"-jar",
"<YOUR_PATH_TO_LUCENESERVER_0_1_SNAPSHOT>"
]
}
}
}<YOUR_PATH_TO_LUCENESERVER_0_1_SNAPSHOT> is the absolute path of your JAR.
