commit: 34a2183b392a27ec56dd9c5f6d96cb667100a23f
[log]
author: Aditya Parikh <aditya.m.parikh@gmail.com>
Tue Aug 18 17:09:13 2026 -0400
committer: GitHub <noreply@github.com>
Tue Aug 18 17:09:13 2026 -0400
tree: 6733acc03fa4b043f54cd28e1561f240b9f5ece5
parent: 69a23a9d50f53b17e6727ca539641e289d78c63b [diff]

docs: fix broken documentation links in README (#171)

* docs: fix broken documentation links in README (#168)

The README merged in #151 links into docs/site/content/pages/mcp/, a tree
that only exists on the unmerged #143 branch, so every documentation link
on main 404s.

Restore the linked content from the #143 branch into locations that exist
on main today, adapted for plain GitHub rendering (Pelican frontmatter
converted to headings, site-absolute links repointed):

- per-client setup guides (Claude Desktop, Claude Code, VS Code/Copilot,
  Cursor, JetBrains, MCP Inspector) under docs/clients/
- observability guide at docs/observability.md

and repoint the README links there; the Quick start link now targets the
README's own section.

Also fix three pre-existing broken links found by a repo-wide sweep:

- docs/security/http.md and docs/security/stdio.md referenced
  ../specs/graalvm-native-image.md, which moved to dev-docs/
- docs/security/keycloak.md TOC listed a 'User Federation (LDAP/AD)'
  section that does not exist

This does not preempt the #143 discussion about where website source
should live; when that lands these files can move wherever dev@ decides.

Fixes #168

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

* docs(clients): fix dead 'running-the-server' README anchor in client guides

Five client guides linked to
https://github.com/apache/solr-mcp#running-the-server, an anchor for a
README section that no longer exists (removed by the #151 slim-down).
Absolute self-links also dodge relative-link checkers, which is how this
survived the sweep.

- claude-desktop.md: point the built-JAR reference at the README's
  Quick start section via a relative link
- claude-code/cursor/vs-code/jetbrains: inline the HTTP-mode start
  command instead of linking (the current README has no HTTP-mode
  startup section to link to)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

* docs: apply review suggestions — JetBrains transport, dead links, clients index

- jetbrains.md: the IDE Settings transport is HTTP, not SSE — AI
  Assistant connects via streamable HTTP, which is what this server
  implements (stateless streamable, POST /mcp); the legacy SSE
  transport is not served. Verified against the current JetBrains
  AI Assistant MCP documentation, and repointed the guide's doc link
  there (help/idea/model-context-protocol.html now 404s).
- README: spec.modelcontextprotocol.io is a dead host (TLS failure;
  retired spec subdomain) — point the MCP link at
  modelcontextprotocol.io. All other external links in the PR's
  files verified 200.
- Add docs/clients/README.md so the README's 'Client setup'
  directory link lands on an index instead of a bare file listing.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

---------

Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

README.md[diff]
docs/clients/README.md[Added - diff]
docs/clients/claude-code.md[Added - diff]
docs/clients/claude-desktop.md[Added - diff]
docs/clients/cursor.md[Added - diff]
docs/clients/jetbrains.md[Added - diff]
docs/clients/mcp-inspector.md[Added - diff]
docs/clients/vs-code.md[Added - diff]
docs/observability.md[Added - diff]
docs/security/http.md[diff]
docs/security/keycloak.md[diff]
docs/security/stdio.md[diff]

12 files changed

tree: 6733acc03fa4b043f54cd28e1561f240b9f5ece5

README.md

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, VS Code/Copilot, Cursor, JetBrains) can invoke.

Quick start

Prerequisites: Java 25+, Docker and Docker Compose, Git.

Compatibility: works with Apache Solr 8.11–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 · VS Code / Copilot · Cursor · JetBrains · 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 from a JSON string into a collection
`index-csv-documents`	Index documents from a CSV string into a collection
`index-xml-documents`	Index documents from an XML string into a collection
`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

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.

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 and metrics env vars (OTEL_SAMPLING_PROBABILITY, OTEL_TRACES_URL) are covered in Observability.

Documentation

Using it

Quick start · Client setup — Claude Desktop, Claude Code, VS Code, Cursor, JetBrains, MCP Inspector
Observability — OpenTelemetry traces, metrics, logs
Security: Deployment model (single-tenant) · STDIO model · HTTP model · OAuth2 setup: Auth0 · Keycloak

Developing it

Development guide — build, run, test, IDE, native image, SBOM · Architecture
Deployment — Docker images, the three-image matrix, registries, Kubernetes · Troubleshooting
GraalVM native image spec · Contributing

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

Website: https://solr.apache.org/mcp
Slack: #solr-mcp in the the-asf workspace
Mailing lists: Shared with Apache Solr — see mailing lists
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, Apache Solr, Jib, Paketo Buildpacks, Testcontainers, and Spring AI MCP Security.