Skip to main content
Glama

docsearch-mcp

Local document search with cited sources, as an MCP server and a web app. It uses BM25 ranking implemented in pure Python: no API key, no model download, no vector database.

demo

Why

Agents need grounded context they can cite. This gives any MCP client two tools, search_docs and list_sources, over your own folder of .md/.txt/.rst files, with the source and a relevance score returned for every chunk so answers can be traced back.

Related MCP server: docs-search-mcp

Run the demo

pip install -e ".[dev]"
docsearch-web                      # http://127.0.0.1:8000

The default corpus is the docstrings of ~70 Python standard-library modules (about 1,000 chunks), so it works with nothing to configure. Try "run subprocess and capture output" or "compute sha256 hash".

Search your own documents instead:

DOCSEARCH_DIR=./my-docs docsearch-web

Use it from an MCP client

{ "mcpServers": { "docsearch": { "command": "docsearch-mcp-server",
                                  "env": { "DOCSEARCH_DIR": "/path/to/docs" } } } }

Tool

Returns

search_docs(query, k=5)

Top-k chunks: source, chunk, score, text

list_sources()

Number of chunks and the list of source documents

How it works

Documents are split into ~120-word chunks on paragraph boundaries. Chunks are tokenized (lowercased, stopwords removed; the source name is indexed too) and ranked with Okapi BM25 (k1=1.5, b=0.75).

Tests

python -m pytest        # 10 tests
ruff check src tests

Limitations

  • Lexical matching only: a query must share words with the text. It does not understand synonyms the way embedding search can.

  • The index is rebuilt in memory at startup, which suits small and medium corpora.

  • Plain-text formats only (no PDF or HTML parsing).

Available Tools

2 tools
list_sourcesC

Number of indexed chunks and the list of source documents.

Inputs: no named parameters. Returns: object

search_docsA

Search the indexed documents with BM25. Returns the top k chunks with their source, relevance score and text, so answers can cite the source.

Inputs: query (required), k. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct purposes: one searches content by relevance, the other enumerates indexed sources. There is no realistic way to confuse a BM25 search with listing sources.

    Naming Consistency5/5

    Both names follow the same verb_noun snake_case pattern (search_docs, list_sources). The convention is predictable and readable.

    Tool Count3/5

    Two tools is thin for a search server; useful capabilities like fetching a full document or filtering search by source are absent. Still, the count is not absurd for a narrowly scoped read-only index.

    Completeness3/5

    Core retrieval and source enumeration are covered, but there is no way to retrieve a whole document, filter searches by source, or manage the index. Agents hitting a chunk boundary or needing document-level context will dead-end.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables fast local hybrid search over a folder of markdown files via MCP, combining BM25 and vector similarity with explicit relevance verdicts and no LLM or network calls at query time.
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI clients to search and read a folder of Markdown/text documents via a read-only MCP server with hybrid BM25 and local embedding search, treating the calling model as untrusted.
      13 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Semantic code search for any MCP client: indexes local folders of code and docs and answers plain-language or code queries with matching passages, file paths, line ranges and scores. Embedding runs on the local CPU with the Motherlode code-search encoder, so no file content leaves the machine; the encoder downloads once from Hugging Face. Install: npx -y blackwindow-weave-mcp.
      4
      87 npm
      1
      Business Source 1.1
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to search local text and Markdown collections using keyword BM25, semantic vector search, and reranked hybrid retrieval, with full-document retrieval and collection status over MCP.
      883 PyPI
      MIT