Skip to main content
Glama

docs-mcp

CI

An MCP server that gives AI assistants (Claude Code, Claude Desktop, Cursor) fast, cited search over any folder of markdown docs. Point it at a directory, and the assistant gets three read-only tools: search_docs, get_section and list_docs. There's no model, API key or database.

Why

Coding assistants are much better when they can look things up in your docs instead of guessing from training data. Model Context Protocol makes that a small, standard server. This one indexes markdown by heading section, ranks with BM25 and returns section ids, so the assistant can read the exact section it cites.

Related MCP server: DocDex

Tools

Tool

Input

Returns

search_docs

query, limit (1 to 20, default 5)

The best sections: path, heading path, id and snippet. Also returned as structuredContent.

get_section

id

The full text of one section

list_docs

prefix (optional)

Pages with titles and section counts

All three are marked readOnlyHint. Logs go to stderr, because stdout carries the protocol.

Quickstart

pnpm install && pnpm build
node examples/search.mjs ./path/to/docs "how do I deploy with docker"

Claude Code

claude mcp add docs -- node /absolute/path/to/docs-mcp/dist/cli.js /absolute/path/to/your/docs

Claude Desktop or Cursor (claude_desktop_config.json or .cursor/mcp.json)

{
  "mcpServers": {
    "docs": {
      "command": "node",
      "args": ["/absolute/path/to/docs-mcp/dist/cli.js", "/absolute/path/to/your/docs"]
    }
  }
}

Docker: docker run -i --rm -v "$PWD/docs:/docs:ro" docs-mcp

Example

Real output from examples/search.mjs on the FastAPI docs (157 pages, 1,176 sections). Indexing and answering took 0.29 s in total:

$ node examples/search.mjs ../rag-eval-lab/data/corpus/fastapi "how do I make a query parameter optional"
tools: search_docs, get_section, list_docs

1. tutorial/query-param-models.md :: Query Parameter Models > Optional Query Parameter Models
   ## Optional Query Parameter Models Declare a query parameter model with `| None` and a default of `None` to make the group optional. …
2. tutorial/header-param-models.md :: Header Parameter Models > Optional Header Parameter Models
3. tutorial/cookie-param-models.md :: Cookie Parameter Models > Optional Cookie Parameter Models

examples/eval.mjs scores the server's search on the 100-question eval set from rag-eval-lab over the same FastAPI docs. A hit is a section from the right page whose heading path is the answering section or one inside it:

Search

Hit@1

Hit@5

Hit@10

MRR@10

Time per question

docs-mcp BM25 (this repo)

56%

85%

92%

0.683

0.5 ms

Postgres full-text, heading chunks (rag-eval-lab)

30%

67%

84%

0.481

7 ms

Vector search, heading chunks (rag-eval-lab)

62%

88%

95%

0.729

8 ms

BM25 with heading words weighted twice gets most of the way to vector search, with no model and in about half a millisecond. It also does far better than Postgres's ts_rank_cd, which is not BM25. The rag-eval-lab numbers judge relevance by character overlap rather than heading paths, so treat the comparison as close but not exact.

Design decisions

  • ADR-0001: BM25 first, no embeddings.

  • ADR-0002: heading sections and read-only tools.

Limitations

  • Keyword search misses paraphrases that share no words with the docs. For those, rag-eval-lab shows that vector search plus re-ranking does better (Hit@1 72%).

  • The index is built at startup and kept in memory, so restart the server after the docs change. Large doc sets (tens of thousands of pages) would want a persistent index.

  • Markdown only. Setext headings (underlined with ===) are treated as text.

What I'd do next

  • Optional embeddings for hybrid search, behind a flag, measured with the same eval script.

  • Watch the docs folder and re-index changed files.

  • Expose pages as MCP resources as well as tools.

License

MIT

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Turns a directory of markdown documentation into searchable, citable tools for AI assistants, enabling targeted retrieval of specific sections with stable references.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Lets AI agents search and read a folder of Markdown documentation at query time, exposing heading-level search, whole-page or section retrieval, and page listing as tools and resources over stdio or Streamable HTTP. Can run as a CLI, a hosted endpoint, or a library inside an existing Node or Next.js site.
      3
      206 npm
      1
      MIT