Solr MCP Server
Search, index, and manage Apache Solr collections using natural language — no need to hand-craft Solr queries, build filter expressions, or memorize the admin API.
Instead of writing:
q=title:"star wars" AND genre_s:"sci-fi"&fq=year_i:[2000 TO *]&facet=true&facet.field=genre_s&sort=score desc&rows=10
Just ask your AI assistant:
"Find sci-fi movies with 'star wars' in the title released after 2000, show me the genre breakdown, and sort by relevance."
This Spring AI Model Context Protocol (MCP) server exposes Solr operations as tools that any MCP-compatible AI client (Claude Desktop, Claude Code, Codex, ChatGPT, VS Code/Copilot, Cursor, JetBrains, Zed) can invoke.
Quick start
Prerequisites: Java 25+, Docker and Docker Compose, Git.
Compatibility: works with Apache Solr 9.4–10 (the test suite runs against 9.9 by default — see Solr version compatibility).
1. Start Solr with sample data
git clone https://github.com/apache/solr-mcp.git
cd solr-mcp
docker compose up -d
This starts Solr in SolrCloud mode with two sample collections: films (1,100+ movies) and books (empty, ready for indexing). Wait ~30 seconds, then verify at http://localhost:8983/solr/.
2. Build the server
./gradlew build
This produces build/libs/solr-mcp-1.0.0-SNAPSHOT.jar.
3. Connect your AI client
Add the server to your MCP client. For Claude Desktop, edit
~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or
%APPDATA%\Claude\claude_desktop_config.json (Windows), then restart Claude:
{
"mcpServers": {
"solr-mcp": {
"command": "java",
"args": ["-jar", "/absolute/path/to/solr-mcp/build/libs/solr-mcp-1.0.0-SNAPSHOT.jar"],
"env": { "SOLR_URL": "http://localhost:8983/solr/" }
}
}
}
Using a different client, or want STDIO/HTTP/Docker options? See the per-client guides:
Claude Desktop ·
Claude Code ·
Codex ·
ChatGPT (HTTP only) ·
VS Code / Copilot ·
Cursor ·
JetBrains ·
Zed ·
MCP Inspector.
4. Try it out
- "What collections are available in Solr?"
- "Search the films collection for movies directed by Steven Spielberg"
- "Show me the schema for the films collection"
- "Index this JSON into the books collection: [{"id": "1", "title": "The Great Gatsby", "author": "F. Scott Fitzgerald"}]"
Example prompts
Searching
- "Find sci-fi movies released after 2000 and show the genre breakdown"
- "Search films for movies with 'war' in the title, sorted by year"
- "Show me the top 5 most recent films"
Indexing
- "Index this JSON into the books collection: [{"id": "1", "title": "1984", "author": "George Orwell"}]"
- "Create a new collection called products"
Managing
- "Is the films collection healthy?"
- "How many documents are in the films collection?"
- "Show me the schema for the films collection"
What you can do
Tools
| Tool | Description |
|---|
search | Full-text search with filtering, faceting, sorting, and pagination |
index-json-documents | Index documents passed as a JSON array of objects into a collection |
index-csv-documents | Index documents from a CSV string via Solr's CSV handler; repeat a column name for multi-valued fields |
index-xml-documents | Index documents from Solr update XML (<add><doc><field name="...">); only <add> blocks are accepted |
index-markdown-documents | Index markdown documents into a collection (one array element per document), extracting front matter, title, headings, and body text |
create-collection | Create a collection (configSet, numShards, replicationFactor optional — default _default, 1, 1) |
list-collections | List all available Solr collections |
get-collection-stats | Get statistics and metrics for a collection |
check-health | Check the health status of a collection |
add-fields | Add fields to a collection schema (additive only; existing fields cannot be modified) |
add-field-types | Add field types — custom analyzers, DenseVectorField for semantic search, etc. |
get-schema | Retrieve schema information for a collection |
list-aliases | List all Solr aliases and the collections they point to |
create-alias | Create or update a Solr alias pointing to one or more collections |
delete-alias | Delete a Solr alias (underlying collections are not affected) |
Every tool advertises MCP behavior hints (readOnlyHint, destructiveHint, idempotentHint) so clients can build sensible approval UX — search and the metadata tools are read-only, indexing is destructive but idempotent, schema modification is additive.
Resources
| Resource URI | Description |
|---|
solr://collections | List of all Solr collections in the cluster |
solr://{collection}/schema | Schema definition for a collection (supports autocompletion) |
Prompts
Slash-command-style workflow templates that walk the assistant through a canonical Solr workflow.
| Prompt | Arguments | Purpose |
|---|
explore-collections | — | List collections and characterise each by stats and health |
setup-collection | name, purpose (optional) | Pick configset / shards / replication factor, create the collection, verify it |
view-schema | collection | Read-only schema walkthrough |
design-schema | collection, datasetDescription, sampleDocument (optional) | Choose field types and apply additive schema changes |
index-data | collection, format (json / csv / xml), sample (optional) | Pick the right indexing tool and confirm the result |
search-collection | collection, question | Translate a natural-language question into a Solr query |
Completions
The server implements MCP argument autocompletion, so clients can suggest valid values as you type:
- Resource argument — the
{collection} segment of solr://{collection}/schema completes to live collection names.
- Prompt arguments — the
collection argument of the search-collection, index-data, view-schema, and design-schema prompts completes to live collection names.
Suggestions are matched case-insensitively by prefix and capped per request.
Screenshots
Claude Desktop (STDIO) — answering a question about the films collection with the server's tools:
STDIO — the Inspector launches the server with java -jar; the protocol log shows the tool, prompt and resource lists coming back:
HTTP — connected over Streamable HTTP at http://localhost:8080/mcp. Without a token the client connects and lists tools; calling them needs a bearer token:
HTTP with OAuth2 — the bearer token goes in the server's Settings → Custom Headers:
With a valid token, tool calls succeed — here check-health on films:
Without one, every tool call returns Access Denied:
Resources — reading solr://collections:
Completions — the {collection} argument of solr://{collection}/schema completes to live collection names:
Prompts — the collection argument of search-collection completes the same way:
Configuration
The server reads configuration from environment variables. The essentials:
| Variable | Description | Default |
|---|
SOLR_URL | Solr base URL | http://localhost:8983/solr/ |
PROFILES | Transport mode: stdio (default, for Claude Desktop) or http (remote / multi-client) | stdio |
Running in HTTP mode — OAuth2, CORS, and the HTTP_SECURITY_ENABLED toggle (secured by default) — is covered in the security docs. Tracing, metrics and log-export env vars (OTEL_SAMPLING_PROBABILITY, OTEL_TRACES_URL, OTEL_METRICS_URL, OTEL_LOGS_URL) are covered in Observability.
Documentation
Using it
- Quick start · Client setup — Claude Desktop, Claude Code, Codex, ChatGPT, VS Code, Cursor, JetBrains, Zed, MCP Inspector
- Tutorial: your first collection — index a dataset twice, schemaless then with a designed schema, and see why field types matter
- Observability — OpenTelemetry traces, metrics, logs
- Security: Deployment model (single-tenant) · STDIO model · HTTP model · OAuth2 setup: Auth0 · Keycloak
Developing it
Container images: published images are not yet available on a public registry. The Docker examples in the client guides use a locally built image — build it with ./gradlew jibDockerBuild (produces solr-mcp:latest). See Building Docker images.
Community
License
Apache License 2.0 — see LICENSE.
Acknowledgments
Built with Spring AI MCP, Apache Solr, Jib, Paketo Buildpacks, Testcontainers, and Spring AI MCP Security.
