Opensolr MCP Server

opensolr-mcp

mcp-name: com.opensolr/opensolr-mcp

MCP (Model Context Protocol) server for Opensolr — gives any AI agent managed Apache Solr search as tools: hybrid (BM25 + kNN) retrieval, server-side GPU embeddings, document indexing, and grounded RAG answers.

See it live (real news index, hybrid + AI answer): https://search.opensolr.com/news__dense?q=how+am+I+supposed+to+save+money%3F

No embedding model to configure. No vector database to run. One API key.

Tools

Setup

Get a free Opensolr account (free forever, no card) at opensolr.com/register and copy your API key from Account.

Try it without an account

There is a public demo account. Point the package at it and everything in this README works immediately, with no signup:

export OPENSOLR_EMAIL=mcp@opensolr.com
export OPENSOLR_API_KEY=420b8b23e7b12dc8ab838932145a5065

mcp_demo_d1__dense is already loaded with 300 news articles, so search, filtering and grounded answers work the moment you connect. You also get the full write path: create your own index on the account, ingest into it, query it, delete it.

Know what you are working with:

• Anything you create there is deleted after 3 days. Automatically, without warning or export. That includes indexes you created and every document in them.
• The account is shared with everyone reading this. Your index is visible to them, they can change or delete it, and you can do the same to theirs. Never put anything real, private or client-owned in it.
• The limits are per index, and deliberately small. 200 MB of bandwidth and 50 MB of disk per index. Bandwidth is the one you will hit first: it covers a demo, a tutorial and a proof of concept, and it will not carry an application.

When you want an index that is private, yours and still there next week, get your own key — free forever, no card — and change the two variables above. Nothing else in your code changes.

Claude Desktop / Claude Code

{
  "mcpServers": {
    "opensolr": {
      "command": "uvx",
      "args": ["opensolr-mcp"],
      "env": {
        "OPENSOLR_EMAIL": "you@example.com",
        "OPENSOLR_API_KEY": "YOUR_OPENSOLR_API_KEY"
      }
    }
  }
}

Cursor / Windsurf / any MCP client

Same shape — stdio transport, command uvx opensolr-mcp (or pipx run opensolr-mcp), with OPENSOLR_EMAIL and OPENSOLR_API_KEY in env.

Example agent session

You: Index our FAQ answers, then find everything about refunds.

The agent calls opensolr_add_documents(index="faq__dense", texts=[...]), then opensolr_search(index="faq__dense", query="refund policy", hybrid=True) — BM25 catches the exact word "refund", kNN catches "giving customers their money back", and the scores fuse per document.

Search with a photo

opensolr_search_by_image lets the agent search with a picture instead of a text query. Opensolr reads the image three ways — visual labels (what it depicts), OCR text (words printed on it), and any barcode / QR code — turns that into words, and runs the normal search. No image vector is stored.

opensolr_search_by_image(index="catalog__dense", image_path="/tmp/shelf.jpg",
                         using="auto", k=5)
# using: "auto" (engine's choice) | "meaning" (visual labels) |
#        "text" (OCR only) | "code" (exact barcode/QR) | "all" (everything)
# -> { "read": {text, mode, labels, codes}, "results": [...] }

search_mode, mode, alpha, fresh_bias and filter_query behave exactly as in opensolr_search.

Search operators

The query string understands the operators people already expect from a search box. They work in every mode — keyword, hybrid and pure vector.

They compose: +laptop +"13 inch" -refurbished returns only 13-inch laptops and never a refurbished one.

A prefixed term (+ or -, word or phrase) becomes a filter, applied to the whole result set. That matters as soon as a vector is involved: the semantic side of a hybrid search has no concept of negation, so left as query text -refurbished would actually pull refurbished listings towards the top rather than removing them. As a filter it binds every document, whichever side of the search found it, and the exclusion is absolute.

An unprefixed phrase ("machine learning" with no + in front) is a keyword-side relevance signal rather than a filter — use +"machine learning" when you need it enforced.

+ and - only count at the start of a word, so e-mail, covid-19 and 1+1 are searched for literally.

Notes

• Vector-enabled indexes run on Opensolr's Solr 9.x environments — currently us (Chicago), de (Germany), fi (Finland), fetched live via opensolr_vector_regions. Additional dedicated regions can be deployed on request (paid add-on): support@opensolr.com.
• Every index is also plain Apache Solr with the native /select API — nothing is locked behind the tools.
• Python sibling for LangChain: langchain-opensolr · Product page: opensolr.com/langchain

How writing works (Data Ingestion API)

Writes go through Opensolr's Data Ingestion API — the same pipeline the Drupal and WordPress connectors use. It is asynchronous: documents are queued, then embeddings, sentiment, language and all crawler-identical derived fields are computed server-side, and documents become searchable within about a minute. Progress is visible in Control Panel → Data Ingestion — a per-job status board (queued / processing / completed / failed, with processed / success / failed document counts per job) — and via the ingest_status API. Each document's identity is its uri (the Solr id is md5(uri)): pass a real URL in metadata ({"uri": "https://..."}), or a deterministic one is synthesized from your id. Re-submitting the same uri updates the document. Pass {"rtf": True, "uri": "https://.../file.pdf"} and the server extracts the text from PDF/DOCX/XLSX for you.

Lexical-only mode

Don't need vectors? Pure keyword search skips the embedding call entirely — zero AI quota, and it works on any Opensolr index, including non-vector ones and older Solr versions.

Your index schema

Documents follow the Opensolr document model (title, description, text, meta_* custom fields). The whole schema, every field and every type suffix, is explained in the Index Schema Reference. To see your own copy: Control Panel → click your index → Configuration → Edit File → schema.xml. Prefer zero-effort data entry? Configure the Web Crawler in the Control Panel (Index Tools → WebCrawler): add your site URL, validate it, and Opensolr indexes the whole site for you.

Search tuning

Retrieval (search and RAG grounding) runs through the platform's tuned pipeline: global defaults → your index's saved Search Tuning (Control Panel → Index Settings → Search Tuning: semantic↔lexical balance, field weights, minimum match, search mode, vector candidate pool, content quality boost) → optional per-call overrides via tuning:

tuning={"search_mode": "keywords_required", "fw_title": 0.2,
        "mm": "strict", "vector_topk": 500, "quality_boost": 0.3}

Defaults match the platform's PHP configuration exactly — customize in the Control Panel once, or per call from code.

Fresh Results Bias

Rank newer documents higher without hiding anything older. Every score is multiplied by a recency curve on creation_date — full weight for a document published today, about half after a year:

store.similarity_search_with_score("solar inverter warranty", fresh_bias=True)
client.hybrid_search(index, query, fresh_bias=True)
client.ai_answer(index, question, tuning={"fresh_bias": 1})

It re-orders and never filters: the hit count is identical either way, nothing old becomes unreachable, and a document with no creation_date simply keeps its place instead of being pushed to the bottom. It applies to all three retrieval shapes — vector-only, keyword-only and the fused hybrid ranking — because the boost wraps the final score rather than one half of it. Off by default.

This is the same control visitors get as the Fresh toggle beside the sort options on the hosted Opensolr search page, so a query behaves identically here and there.

fresh_bias and freshness_boost are two different knobs and the names invite confusion. freshness_boost is a hard window in days — anything older is filtered out and the hit count drops. fresh_bias filters nothing.

How it's tested

Every release is validated against live Opensolr infrastructure — no mocks:

• Unit tests (offline): location aliases, filter→fq mapping, query building, escaping.
• End-to-end suite: the full write path through the async Data Ingestion queue (queued → server-side enrichment → searchable), semantic / hybrid / lexical retrieval, metadata round-trip, filters, id round-trip (your ids and the Solr md5(uri) ids), deletes by id and by query.
• Real-corpus validation: searches run against a 340-document replica of opensolr.com's own production search index. Verified: pure-semantic hits with zero keyword overlap ("how do I get my data back after a disaster" → backup & restore docs), cross-lingual queries (Romanian query → English content), exact-term surfacing in hybrid mode, all four hybrid modes, and the full alpha range 0 → 1.
• PDF ingestion: a real PDF ingested via rtf:true — server-side text extraction (13k+ chars), automatic content-type detection, then retrieved with a purely semantic query against its contents.

The tools are exercised live (search modes, ingestion with wait, status, deletes, RAG answers) before every release. RAG grounding is verified end-to-end: a question answerable only from the ingested PDF returns the correct answer sourced from the PDF's extracted text.

MIT license.