Solr MCP Server

A Spring AI Model Context Protocol (MCP) server that provides tools for interacting with Apache Solr. Enables AI assistants like Claude to search, index, and manage Solr collections through the MCP protocol.

What's inside

🔍 Search Solr collections with filtering, faceting, and pagination
📝 Index documents in JSON, CSV, and XML
📁 Create collections with configurable shards, replicas, and configsets
📊 Manage collections and view statistics
🔧 Inspect schema
🔌 Transports: STDIO (Claude Desktop) and HTTP (MCP Inspector)
🔐 OAuth2 security with Auth0 (HTTP mode only)
🐳 Docker images built with Jib

Get started (users)

Prerequisites: Java 25+, Docker (and Docker Compose), Git
Start Solr with sample data:
```
docker compose up -d
```

Run the server:

STDIO mode (default):

Gradle:
```
./gradlew bootRun
```

JAR:

./gradlew build
java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar

Docker:

docker run -i --rm ghcr.io/apache/solr-mcp:latest

HTTP mode:

Gradle:
```
PROFILES=http ./gradlew bootRun
```

JAR:

PROFILES=http java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar

Docker:

docker run -p 8080:8080 --rm -e PROFILES=http ghcr.io/apache/solr-mcp:latest

For more options (custom SOLR_URL, Linux host networking) see the Deployment Guide: docs/DEPLOYMENT.md

Claude Desktop

Add this to your Claude Desktop config (macOS path shown); then restart Claude.

STDIO mode (default)

Using Docker:

{
  "mcpServers": {
    "solr-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/apache/solr-mcp:latest"],
        "env": {
            "SOLR_URL": "http://localhost:8983/solr/"
        }
    }
  }
}

Using JAR:

{
    "mcpServers": {
        "solr-mcp": {
            "command": "java",
            "args": [
                "-jar",
                "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"
            ],
            "env": {
                "SOLR_URL": "http://localhost:8983/solr/"
            }
        }
    }
}

HTTP mode

Using Docker:

{
    "mcpServers": {
        "solr-mcp": {
            "command": "docker",
            "args": [
                "run",
                "-p",
                "8080:8080",
                "--rm",
                "ghcr.io/apache/solr-mcp:latest"
            ],
            "env": {
                "PROFILES": "http",
                "SOLR_URL": "http://localhost:8983/solr/"
            }
        }
    }
}

Using JAR:

{
    "mcpServers": {
        "solr-mcp": {
            "command": "java",
            "args": [
                "-jar",
                "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"
            ],
            "env": {
                "PROFILES": "http",
                "SOLR_URL": "http://localhost:8983/solr/"
            }
    }
  }
}

Connecting to a running HTTP server

If you already have the MCP server running in HTTP mode (via Gradle, JAR, or Docker), you can connect Claude Desktop to it using mcp-remote:

Running via Gradle:

PROFILES=http ./gradlew bootRun

Running locally (JAR):

PROFILES=http java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar

Running via Docker:

docker run -p 8080:8080 --rm -e PROFILES=http ghcr.io/apache/solr-mcp:latest

Then add to your claude_desktop_config.json:

{
    "mcpServers": {
        "solr-mcp-http": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "http://localhost:8080/mcp"
            ]
        }
    }
}

More configuration options: see the Building Docker images section below.

Claude Code

Add Solr MCP to Claude Code using the CLI or by adding a .mcp.json file to your project root.

STDIO mode (default)

Using Docker (CLI):

claude mcp add --transport stdio solr-mcp -- docker run -i --rm ghcr.io/apache/solr-mcp:latest

Using JAR (CLI):

claude mcp add --transport stdio -e SOLR_URL=http://localhost:8983/solr/ solr-mcp -- java -jar /absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar

Or add to your project's .mcp.json:

Using Docker:

{
  "mcpServers": {
    "solr-mcp": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/apache/solr-mcp:latest"],
      "env": {
        "SOLR_URL": "http://localhost:8983/solr/"
      }
    }
  }
}

Using JAR:

{
  "mcpServers": {
    "solr-mcp": {
      "type": "stdio",
      "command": "java",
      "args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"],
      "env": {
        "SOLR_URL": "http://localhost:8983/solr/"
      }
    }
  }
}

HTTP mode

Start the server first (pick one):

# Gradle
PROFILES=http ./gradlew bootRun

# JAR
PROFILES=http java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar

# Docker
docker run -p 8080:8080 --rm -e PROFILES=http ghcr.io/apache/solr-mcp:latest

Then add to Claude Code:

claude mcp add --transport http solr-mcp http://localhost:8080/mcp

Or add to .mcp.json:

{
  "mcpServers": {
    "solr-mcp": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Security (OAuth2)

The Solr MCP server supports OAuth2 authentication when running in HTTP mode, providing secure access control for your MCP tools.

Features

OAuth2 Resource Server: JWT token validation using Auth0 (or any OAuth2 provider)
HTTP Mode Only: Security is only active when using the http profile
CORS Support: Enabled for MCP Inspector compatibility
Machine-to-Machine: Uses Client Credentials flow for service authentication

Quick Setup

Configure Auth0 (see detailed guide: security-docs/AUTH0_SETUP.md)
- Create an Auth0 Application (Machine to Machine)
- Create an Auth0 API with your audience identifier
- Note your Domain, Client ID, Client Secret, and Audience

Set Environment Variable:

export OAUTH2_ISSUER_URI=https://your-tenant.auth0.com/
export PROFILES=http

Run the Server:
```
./gradlew bootRun
```

Get Access Token (using convenience script):

./scripts/get-auth0-token.sh --domain your-tenant.auth0.com \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET \
  --audience https://solr-mcp-api

Use the Token:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8080/mcp

For complete setup instructions, see security-docs/AUTH0_SETUP.md

Available MCP tools

Search

Tool	Description
`search`	Full-text search with filtering, faceting, sorting, and pagination

Indexing

Tool	Description
`index-json-documents`	Index documents from a JSON string into a Solr collection
`index-csv-documents`	Index documents from a CSV string into a Solr collection
`index-xml-documents`	Index documents from an XML string into a Solr collection

Collections

Tool	Description
`create-collection`	Create a new Solr collection (configSet, numShards, replicationFactor optional — default to `_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

Schema

Tool	Description
`get-schema`	Retrieve schema information for a collection

Available MCP Resources

MCP Resources provide a way to expose data that can be read by MCP clients. The Solr MCP Server provides the following resources:

Resource URI	Description
`solr://collections`	List of all Solr collections available in the cluster
`solr://{collection}/schema`	Schema definition for a specific collection (supports autocompletion)

Resource Autocompletion

The solr://{collection}/schema resource supports autocompletion for the {collection} parameter. MCP clients can use the completion API to get a list of available collection names.

Screenshots

Claude Desktop (STDIO):
MCP Inspector (HTTP):
MCP Inspector (HTTP with OAuth2 - Success):
MCP Inspector (HTTP with OAuth2 - Failure):
MCP Inspector (STDIO):

Building Docker images

Three image artifacts cover the full transport × runtime matrix. The JVM image is built with Jib (clean stdout, multi-arch); the native variants are built with Paketo Cloud Native Buildpacks.

Image	Toolchain	Build command	STDIO	HTTP
`solr-mcp:<version>`	Jib	`./gradlew jibDockerBuild`	✅	✅
`solr-mcp:<version>-native-stdio`	Paketo	`./gradlew bootBuildImage -Pnative`	✅	❌
`solr-mcp:<version>-native-http`	Paketo	`./gradlew bootBuildImage -Pnative -Pprofile=http`	❌	✅

Run commands

# STDIO — Jib JVM (default profile is stdio)
docker run -i --rm \
    -e SOLR_URL=http://host.docker.internal:8983/solr/ \
    solr-mcp:latest

# STDIO — native (faster startup, smaller image)
docker run -i --rm \
    -e SOLR_URL=http://host.docker.internal:8983/solr/ \
    solr-mcp:latest-native-stdio

# HTTP — Jib JVM
docker run -p 8080:8080 --rm \
    -e PROFILES=http \
    -e SOLR_URL=http://host.docker.internal:8983/solr/ \
    solr-mcp:latest

# HTTP — native
docker run -p 8080:8080 --rm \
    -e PROFILES=http \
    -e SOLR_URL=http://host.docker.internal:8983/solr/ \
    solr-mcp:latest-native-http

Why three images

Jib's JVM image is dual-mode because Jib uses a clean java -jar entrypoint with no launcher script. Stdout stays clean for MCP STDIO, and runtime PROFILES=http switches to web mode.
Paketo's JVM image is unsuitable for stdio — its libjvm helpers (memory calculator, NMT, ca-certificates) write 6 lines to stdout before the JVM, breaking MCP's JSON-RPC stream. Verified end-to-end by DockerImageMcpClientStdioIntegrationTest (Spring AI MCP client times out on initialize()). Filed upstream as paketo-buildpacks/libjvm#482. We use Jib for the JVM image instead.
Native images must AOT-pin to one profile. Spring AOT bakes spring.main.web-application-type into the binary at AOT time. Activating both profiles picks servlet (http overrides stdio), which forces Tomcat to start regardless of the runtime PROFILES value, breaking stdio. So we ship one native image per transport.

Claude Desktop (native, STDIO)

{
  "mcpServers": {
    "solr-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SOLR_URL=http://host.docker.internal:8983/solr/",
        "solr-mcp:latest-native"
      ]
    }
  }
}

See docs/specs/graalvm-native-image.md for the native image design and known risks.

Documentation

Contributing

We welcome contributions!

Start here: CONTRIBUTING.md

Support

Issues: https://github.com/apache/solr-mcp/issues
Discussions: https://github.com/apache/solr-mcp/discussions

License

Apache License 2.0 — see LICENSE

Acknowledgments

Built with:

Spring AI MCP — https://spring.io/projects/spring-ai
Apache Solr — https://solr.apache.org/
Jib — https://github.com/GoogleContainerTools/jib
Paketo Cloud Native Buildpacks — https://paketo.io/
Testcontainers — https://www.testcontainers.org/
Spring AI MCP Security — https://github.com/spring-ai-community/mcp-security

Name		Name	Last commit message	Last commit date
Latest commit History 173 Commits
.github		.github
.run		.run
dev-docs		dev-docs
docs		docs
gradle		gradle
images		images
mydata		mydata
scripts		scripts
security-docs		security-docs
src		src
.asf.yaml		.asf.yaml
.editorconfig		.editorconfig
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
TESTING_DISTRIBUTED_TRACING.md		TESTING_DISTRIBUTED_TRACING.md
build.gradle.kts		build.gradle.kts
compose.yaml		compose.yaml
gradlew		gradlew
gradlew.bat		gradlew.bat
init-solr.sh		init-solr.sh
server.json		server.json
settings.gradle.kts		settings.gradle.kts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Solr MCP Server

What's inside

Get started (users)

Claude Desktop

Claude Code

Security (OAuth2)

Features

Quick Setup

Available MCP tools

Search

Indexing

Collections

Schema

Available MCP Resources

Resource Autocompletion

Screenshots

Building Docker images

Run commands

Why three images

Claude Desktop (native, STDIO)

Documentation

Contributing

Support

License

Acknowledgments

About

Uh oh!

Releases

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Solr MCP Server

What's inside

Get started (users)

Claude Desktop

Claude Code

Security (OAuth2)

Features

Quick Setup

Available MCP tools

Search

Indexing

Collections

Schema

Available MCP Resources

Resource Autocompletion

Screenshots

Building Docker images

Run commands

Why three images

Claude Desktop (native, STDIO)

Documentation

Contributing

Support

License

Acknowledgments

About

Topics

Resources

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages