The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Opensolr MCP listing page.
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.
| 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) |
Get a free Opensolr account (free forever, no card) at opensolr.com/register and copy your API key from Account.
There is a public demo account. Point the package at it and everything in this README works immediately, with no signup:
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:
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.
Same shape — stdio transport, command uvx opensolr-mcp (or
pipx run opensolr-mcp), with OPENSOLR_EMAIL and OPENSOLR_API_KEY in env.
You: Index our FAQ answers, then find everything about refunds.
The agent calls
opensolr_add_documents(index="faq__dense", texts=[...]), thenopensolr_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.
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.
search_mode, mode, alpha, fresh_bias, filter_query, date_from, date_to
and group_pages behave exactly as in opensolr_search.
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.
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.wait_seconds comes back under pending; call the tool again with the same path
to index those (nothing is sent twice).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.
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:
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.
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.
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.
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./select API —
nothing is locked behind the tools.langchain-opensolr ·
Product page: opensolr.com/langchainWrites 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.
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).
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:
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.
See the details, and fix what can be fixed:
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.
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.
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:
Defaults match the platform's PHP configuration exactly — customize in the Control Panel once, or per call from code.
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:
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_biasandfreshness_boostare two different knobs and the names invite confusion.freshness_boostis a hard window in days — anything older is filtered out and the hit count drops.fresh_biasfilters nothing.
Every release is validated against live Opensolr infrastructure — no mocks:
md5(uri) ids), deletes by id and by query.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.