solr-mcp-server

MCP (Model Context Protocol) server for Apache Solr with HTTP Basic Auth.

Exposes Solr search, faceting, document CRUD, collection, and schema operations as MCP tools for use with opencode, Claude, or any MCP-compatible client.

Requirements

• Node.js 20+
• A running Apache Solr instance
• Solr credentials with HTTP Basic Auth

Setup

npm install
npm run build

Create a .env file (see .env.example):

SOLR_URL=http://localhost:8983/solr
SOLR_USERNAME=admin
SOLR_PASSWORD=changeme

Run locally:

npm start

Tests

Run the unit tests (no Solr instance or network required — the query-string builder and client are tested with mocked fetch):

npm test

MCP Tools

| Tool | Description | | --------------- | ------------------------------------------------------- | | solr_search | Full Solr UI-style querying: faceting, sharding, highlighting, stats, spellcheck, terms, grouping, MoreLikeThis, raw param passthrough | | solr_get_document | Fetch a single document by ID | | solr_index | Add/update documents (full replace or atomic set) | | solr_delete | Delete documents by ID or query | | solr_list_collections | List collections | | solr_collection_info | Ping and inspect a collection | | solr_get_schema | Get schema / field definitions |

Querying

solr_search mirrors the Solr Admin UI Query tab. In addition to the base params (q, fq, sort, start, rows, fl, df, defType, debugQuery, timeAllowed, cursorMark, distrib) it supports:

• Sharding: shards, shards.tolerant, _route_
• Faceting: facet.field, facet.query, facet.pivot, facet.limit, facet.mincount, facet.sort, facet.prefix, facet.offset, plus json.facet for the JSON Facet API
• Highlighting: hl, hl.fl, hl.simple.pre, hl.simple.post, hl.fragsize, hl.snippets
• Stats: stats, stats.field
• Spellcheck: spellcheck, spellcheck.q, spellcheck.collate
• Terms: terms, terms.fl, terms.limit, terms.prefix
• Grouping: group, group.field, group.limit, group.ngroups
• MoreLikeThis: mlt, mlt.fl, mlt.count
• Any other param: pass them through rawParams (equivalent of the UI "Raw Query Parameters" box); values may be scalars or arrays, and override typed params with the same key.

Sharding example:

{
  "collection": "products",
  "q": "*:*",
  "shards": "products_shard1_replica1,products_shard2_replica1",
  "shards.tolerant": true
}

Routing example (query only the shard owning a routing key):

{
  "collection": "products",
  "q": "*:*",
  "_route_": "user-42"
}

Grouping + raw params example:

{
  "collection": "products",
  "q": "title:phone",
  "group": true,
  "group.field": "category",
  "rawParams": { "timeAllowed": 5000 }
}

Faceting

solr_search supports faceting by passing facet.field (one or more). Facet params are all optional; setting facet.field automatically enables facet=true.

{
  "collection": "products",
  "q": "*:*",
  "facet.field": ["category", "status"],
  "facet.mincount": 1,
  "facet.limit": 20,
  "facet.sort": "count desc"
}

Response includes facet_counts.facet_fields alongside the matching docs.

For nested/advanced faceting, pass the JSON Facet API spec via json.facet (results appear under facets):

{
  "collection": "products",
  "q": "*:*",
  "json.facet": "{\"platforms\":{\"type\":\"terms\",\"field\":\"platform\",\"facet\":{\"categories\":{\"type\":\"terms\",\"field\":\"category\"}}}}"
}

Updating documents

solr_index both adds and updates. Post a document with an existing id to fully replace it. For partial (atomic) updates, use Solr field modifiers, which pass through unchanged:

{ "id": "1", "title": { "set": "New title" } }

Using with opencode

Add to your opencode config (~/.config/opencode/opencode.json):

{
  "mcp": {
    "solr": {
      "type": "local",
      "command": ["npx", "-y", "solr-mcp-server"],
      "environment": {
        "SOLR_URL": "http://localhost:8983/solr",
        "SOLR_USERNAME": "admin",
        "SOLR_PASSWORD": "changeme"
      },
      "enabled": true
    }
  }
}

For local development, point the command at the built output instead:

"command": ["node", "/abs/path/to/solr-mcp-server/dist/index.js"]

Restart opencode after changing config — MCP servers are loaded once at startup.

Project Layout

src/
  index.ts              # entry point, stdio transport, env config
  solr-client.ts        # Solr HTTP client (Basic Auth)
  types.ts              # shared types
  tools/                # one module per MCP tool registration