Skip to main content
Glama

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 (local files and folders too, PDFs page by page, scans through OCR), 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

Tool

What it does

opensolr_search

Hybrid (keyword + semantic) or pure semantic search, with Solr filters and a date range; a PDF comes back as its best page, with a link that opens it at that page

opensolr_search_by_image

Search with a photo — Opensolr reads its visual labels, OCR text and any barcode/QR, then searches with those words (no image vector stored)

opensolr_read_document

Read one result in full — a PDF page by page, any other document as one text

opensolr_ai_answer

Grounded RAG answer: top hybrid hits become the LLM context — same pipeline as the hosted search UI

opensolr_index_files

Index a local file or a whole folder: PDFs one document per page, Word / RTF / OpenDocument / text / HTML, scans and pictures through OCR

opensolr_extract_text

Read local files without indexing them: text, OCR of their pictures, a PDF page by page

opensolr_describe_image

What a picture shows (a sentence), the text printed on it, its labels and barcodes

opensolr_add_documents

Index plain text + metadata (embedded server-side)

opensolr_delete_documents

Remove documents by id

opensolr_list_indexes / opensolr_index_info

Inspect the account's indexes

opensolr_create_index

Provision a vector index in a region of opensolr_vector_regions (an environment id, or a short form like us matched against that live list)

opensolr_vector_regions

Live list of vector-enabled regions

opensolr_check_schema

Whether an index can do what each tool needs (Data Ingestion, vector and hybrid search, PDF pages, keyword search), and exactly why not

opensolr_apply_schema

Install the Opensolr vector schema on an index of a vector region (replaces its configuration; force when it holds documents)

Related MCP server: RAG MCP Server

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 write path: create your own index on the account, ingest into it and query it. Deletion is not available on this shared key: no index here can be deleted or reconfigured by hand. Whatever you create is removed automatically after 3 days.

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 and they can add documents to it, as you can to theirs. Nobody can delete or reconfigure an index here (that is switched off for this key), but 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, filter_query, date_from, date_to and group_pages behave exactly as in opensolr_search.

Local files and folders: PDFs page by page, scans through OCR

opensolr_index_files indexes a file or a whole folder from the machine the server runs on. Each file is read on Opensolr's servers — its text, the text in its pictures (OCR, more than 100 languages), a short description of the pictures that have no text — and a PDF is indexed one document per page, so a search lands on the page that answers it instead of a 200-page file that mentions it somewhere. Word, RTF, OpenDocument, text, HTML and picture files (scans, photos of documents) are one document each.

opensolr_index_files(index="contracts__dense", path="~/Documents/contracts",
                     pattern="*.pdf", metadata={"team": "legal"})
# -> {"documents": [{path, source, uri, id}], "pending": [], "failed": [], "jobs": [...]}
  • The bytes travel once: a file the account already sent (same content) is not uploaded again, and sending the same files again replaces their documents.

  • Each document's uri is https://ingest.opensolr.com/<index>/<source>, where source is the file's path from the folder you sent (also in meta_source); its date is the file's modification time, so date ranges work on local files too.

  • Big files are read in the background: whatever is still being read after wait_seconds comes back under pending; call the tool again with the same path to index those (nothing is sent twice).

  • Pictures read by OCR count 0.5 of an AI request each; a file read before is free.

opensolr_extract_text does the same reading without indexing anything — the text of each file, a PDF as its pages (page, text, is_ocr, lang) — for an agent that wants to read a contract, a scanned invoice or a folder of reports itself.

opensolr_describe_image answers what a picture shows and what is written on it: caption (a sentence), text (OCR), labels and barcode / QR codes.

PDF pages in search results

On an index where PDFs are stored page by page (files indexed above, PDFs sent to Data Ingestion with rtf, PDFs found by the Web Crawler), opensolr_search returns each PDF once, as its best page:

{"title": "Master services agreement", "page": 14,
 "page_url": "https://example.com/msa.pdf#page=14",   # opens the PDF at that page
 "document_id": "9f2c...",                            # for opensolr_read_document
 "more_pages": [{"page": 3, "page_url": "...#page=3"}, ...],  # its other matching pages
 "matching_pages": 4, "uri": "https://example.com/msa.pdf", ...}

group_pages=false returns the pages as separate results. opensolr_read_document reads any result in full: a PDF as its pages in order (page_from / page_to), any other document as one text.

Searching a period

date_from and date_to (YYYY-MM-DD, both included, either one can be left out) keep only the documents dated in that period (creation_date). They combine with every other option, fresh_bias included.

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.

Operator

Meaning

Example

"word1 word2"

Phrase — those words together, in that order

"machine learning"

+word

Required — every result must contain it

+laptop 15 inch gaming

+"word1 word2"

Required phrase

+"13 inch"

-word

Excluded — drop any document containing it

laptop -refurbished

-"word1 word2"

Excluded phrase

-"open box"

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 indexes live in the vector regions: the Opensolr servers that run the web crawler, whatever their Solr version. The list is live, never written in the package: opensolr_vector_regions returns the regions that take new indexes right now (environment id, country, Solr version). location= takes an environment id from that list, or a short form such as us, de or fi, matched against the live list by environment id or country. 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. It runs on any Opensolr index that has title, description and text fields, including indexes outside the vector regions and older Solr versions (see Index requirements).

Index requirements

Everything this package does runs on an Opensolr index that sits in a vector region and carries the Opensolr vector schema — the configuration every Opensolr vector index runs. An index created through the package (create_index, create_if_missing) has both. An index made elsewhere may not: a server outside the vector regions, or a schema of its own. A vector region is an Opensolr server that runs the web crawler, whatever its Solr version; the regions that take new indexes come from the live vector_regions list, never from a list in the package.

The check is automatic. The first time the package touches an index, it asks the platform once whether that index can do what is asked: one request per index per client, kept for the client's life, never one per search. If the check itself cannot run (a network error, the platform busy), nothing is blocked: the operation runs exactly as it always did, and the check is tried again after 5 minutes. When an index differs from the Opensolr vector schema, a warning is logged once, on the opensolr logger, with the reasons and the fix.

What the check gates — only what cannot work otherwise:

Capability

Needed for

When it is missing

ingestion

Data Ingestion: adding documents and indexing files

The index is outside the vector regions: refused before a document or a byte is sent

vector_search

Vector and hybrid search

The index has no vector field of the right size: refused before any embedding is paid for

pdf_pages

Grouping the pages of a PDF in search results

Results come back ungrouped, as before

keyword_search

Keyword (lexical) search

Never blocked

The errors say exactly what is going on. A blocked operation raises OpensolrSchemaError (a subclass of OpensolrError) with .index, .capability and .report (the full check), and a message with every reason and the fix:

Index 'shop_it' cannot take documents or files through Data Ingestion. Index shop_it
is on IT-SOLR-9-6 (Milano, Italy), which is not a vector region: Data Ingestion,
server-side embeddings and hybrid search run only on the servers of a vector region
(DE-SOLR-9 (Germany, Solr 9.00), FINLAND9 (Finland, Solr 9.60), ...). This index
cannot be made ready: create a new index in one of the vector regions (...), for
example with create_index, and send your documents there.

When Solr itself refuses a request, OpensolrSolrError carries Solr's own reason and the index name; it is still an httpx.HTTPStatusError, so code that caught that before keeps working.

from opensolr_mcp.client import OpensolrClient, OpensolrSchemaError

client = OpensolrClient(email, api_key)
try:
    client.ingest_files("shop_it", "~/Documents/catalog")
except OpensolrSchemaError as e:
    print(e.capability, e.report["fix"]["action"])   # ingestion new_index

See the details, and fix what can be fixed:

client.check_schema("shop_it")   # ready, capabilities, server, Solr version, missing / different fields, problems, fix
client.apply_schema("shop_it", force=False)   # installs the Opensolr vector schema; force=True when the index holds documents

apply_schema exists so an index of a vector region whose configuration was changed, or never set, can take everything this package does without being recreated: it installs the same configuration every Opensolr vector index runs, and replaces the index configuration. An index that already holds documents needs force=True; those documents keep the fields they were written with and must be sent again. An index outside the vector regions cannot take it — create a new index in a region from vector_regions and send your documents there. The package never installs the schema on its own.

In an agent, the same two calls are the tools opensolr_check_schema and opensolr_apply_schema; every other tool runs the check on its own and returns the message above when it refuses.

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 matching against the live region list, 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 &amp; 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.

Available Tools

10 tools
opensolr_add_documentsA

Index plain-text documents via the Opensolr Data Ingestion API.

Ingestion is ASYNC: embeddings, sentiment, and all derived fields are
computed server-side and documents become searchable within about a
minute (progress is visible in the Opensolr Control Panel). With
wait=true (default) this blocks until the job completes. Metadata keys
become filterable meta_* fields; metadata "uri" (a real URL) is used as
the document identity — the Solr id is md5(uri). Returns job info and
the resulting Solr document ids.

Inputs: index (required), texts (required), ids, wait, +1 more. Returns: result

opensolr_ai_answerA

Ask a question and get a grounded RAG answer generated ONLY from the content already indexed in the given Opensolr index. Retrieval runs through the platform's tuned hybrid pipeline (the index's saved Search Tuning applies automatically) — the top rag_docs hits (first rag_words words of text each) become the LLM context, the same pipeline as the hosted search UI. filter_query optionally narrows retrieval with a raw Solr fq expression; instruction optionally replaces the default prompt (e.g. "Answer in German", "Extract a list of people"); tuning optionally overrides retrieval knobs per call. That list is the whole set, not a sample — an abbreviated one reads as everything that is supported, and freshness_boost was invisible to callers because of it: fw_title, fw_description, fw_uri, fw_text, fw_text_t, lexical_weight, vector_weight, vector_topk, search_mode (union / keywords_required / meaning_required / intersection), quality_boost, min_score, freshness_boost, fresh_bias, lexical_norm_k, mm (flexible / balanced / strict or raw Solr mm syntax). freshness_boost and fresh_bias are different knobs despite the names: the first is a hard window in DAYS that filters older documents out, the second only re-orders, multiplying each score by a recency curve on creation_date so recent documents win ties while nothing becomes unreachable.

Inputs: index (required), query (required), tuning, rag_docs, +3 more. Returns: result

opensolr_create_indexB

Create a new vector-enabled Opensolr index. location: us, de, fi, or any environment id from opensolr_vector_regions. Additional dedicated regions can be deployed on request (support@opensolr.com).

Inputs: index (required), location. Returns: result

opensolr_delete_documentsA

Delete documents by ids (Solr ids or your original ids) or by a raw Solr query, e.g. 'meta_category:"drafts"' or '+id:"abc123"'.

Inputs: index (required), ids, query. Returns: result

opensolr_index_infoB

Get connection details for an index: Solr URL, version, environment. (Credentials are intentionally not returned.)

Inputs: index (required). Returns: result

opensolr_ingest_statusB

Status of a Data Ingestion job (state, processed/success/failed doc counts). Also visible in the Opensolr Control Panel.

Inputs: job_id (required). Returns: result

opensolr_list_indexesA

List all search indexes in the connected Opensolr account.

Inputs: no named parameters. Returns: result

opensolr_search_by_imageA

Search an Opensolr index with a PHOTO instead of a text query.

The image at image_path is read three ways by the Opensolr image engine —
visual labels (what it depicts), OCR text (words printed on it), and any
barcode / QR code — and turned into a text query that runs through the normal
search. No image vector is stored; the picture simply becomes words.

using selects which reading drives the search:
  "auto"    the engine's chosen text (OCR text when the picture is mostly text,
            otherwise the visual labels) — the default,
  "meaning" the visual labels (what the picture depicts),
  "text"    only the OCR text read off the picture (empty if none),
  "code"    the first barcode / QR code, matched as an exact keyword.

search_mode / mode / alpha / fresh_bias / filter_query behave exactly as in
opensolr_search. Returns {"read": {text, mode, labels, codes}, "results": [...]}
so the caller sees both what the picture was read as and the matching documents.

Inputs: index (required), image_path (required), k, mode, +5 more. Returns: result

opensolr_vector_regionsA

List the vector-enabled Opensolr environments currently available (Solr 9.x with dense vectors and the hybrid query parser).

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct operation: text search, image search, RAG answering, index listing/info, ingestion lifecycle, deletion, and creation. Even the two search variants are clearly separated by query type, and the supporting region/status tools have unambiguous roles.

    Naming Consistency4/5

    All tools share the opensolr_ prefix and generally follow a verb_noun pattern, but a few names like opensolr_index_info, opensolr_ai_answer, opensolr_ingest_status, and opensolr_vector_regions are noun-style rather than verb-first. The convention is still predictable and readable.

    Tool Count5/5

    Ten tools cover the primary surface of an Opensolr search server: searching, ingesting, managing documents, and managing indexes. The count feels appropriately scoped without redundant or excessive entries.

    Completeness4/5

    Core workflows are well covered: create/list/inspect indexes, ingest and check status, delete documents, search by text or image, and get grounded answers. Minor gaps exist, such as no delete_index operation and no explicit index settings update or single-document fetch, but these are not fatal to typical usage.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Python server that enables AI assistants to perform hybrid search queries against Apache Solr indexes through the Model Context Protocol, combining keyword precision with vector-based semantic understanding.
      20
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      Combines a knowledge graph with RAG (Retrieval-Augmented Generation) capabilities for semantic code indexing and search. Enables creating entity relationships, managing observations, and performing semantic searches across indexed codebases.
      13
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that indexes documents and serves relevant context to LLMs via Retrieval Augmented Generation (RAG).
      36
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A CLI tool and MCP server that turns markdown documentation into a searchable, queryable knowledge base.
      -