Opensolr MCP

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

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/ / , 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.

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 docume