go-docs-mcp

Go-Docs MCP

Install and Go. One command, single binary. Your AI reads any document: PDF, text, Markdown, Office files, EPUB, HTML, notebooks, images.

MCP server for multi-format document access: read, search, extract images, OCR, and fetch documents from URLs via the Model Context Protocol. 13 tools, 14 formats, zero configuration.

go install github.com/drolosoft/go-docs-mcp@latest

That's it. Single binary, starts in milliseconds.

For a deeper look at why an MCP server beats a direct tool, see [Why MCP?](doc/WHY-MCP.md)

---

🏆 Why Go-Docs MCP?

Every other document MCP server handles one format: a PDF server for PDFs, a DOCX server for DOCX. You'd need three separate servers to read three formats.

Go-Docs MCP reads them all from a single binary.

---

📋 Features: 13 Tools

Highlights:

• Fast: mtime-based in-memory caching avoids redundant extraction
• Multi-format: PDF, text, Markdown, CSV, DOCX, XLSX, PPTX, ODT, EPUB, HTML, RTF, Jupyter notebooks and images from one server
• Paged output: offset and max_chars on the text tools, so a 200 MB file never floods the model
• Resources: every document is also a docs:// resource, so Claude Code can @-mention it
• OCR: automatic fallback to tesseract for scanned documents
• Secure: directory-locked with path traversal prevention
• Portable: works on macOS, Linux and Windows

---

📄 Supported Formats

• PDF with poppler, and tesseract for scanned pages
• TXT, MD, CSV with no external program
• DOCX, XLSX, PPTX, ODT, EPUB, HTML, RTF, IPYNB with pandoc
• Images (PNG, JPG, WebP, TIFF, BMP) with tesseract

What each format supports, the type values of list_documents and the limits of a call are in [doc/formats.md](doc/formats.md).

---

🚀 Installation

brew install drolosoft/tap/go-docs-mcp   # macOS and Linux, brings poppler, tesseract and pandoc

Or, with Go 1.27.3 or later, go install github.com/drolosoft/go-docs-mcp@latest and install poppler (plus tesseract and pandoc if you need them) yourself.

Two more ways, both listed in the official MCP Registry:

• Claude Desktop, one click. Download go-docs-mcp_ .mcpb from the latest release and open it. It asks for your documents folder. poppler, tesseract and pandoc still come from your system (brew install poppler tesseract pandoc).
• Docker, nothing to install. The image brings poppler, tesseract (English and Spanish) and pandoc:

  docker run -i --rm -v /path/to/your/documents:/documents:ro ghcr.io/drolosoft/go-docs-mcp

The Claude Code plugin, the release archives and how to check them, the settings of each of these and the commands for each package manager are in [doc/install.md](doc/install.md).

---

⚙️ Configuration

The server reads the documents in DOCS_MCP_DIR (default ~/.docs-mcp/documents/) and finds every supported file in it; files added while it runs show up on the next call. The other settings (OCR language, cache size, read_url switches) are listed in doc/install.md.

Resources

Every document is also exposed as an MCP resource with the URI docs:// (percent-encoded). Clients that support resources, such as Claude Code with @docs://report.pdf, can pull a document into the conversation without calling a tool. The list is rebuilt on every resources/list, so files added after startup show up.

Structured output

list_documents, list_formats, get_document_metadata, get_document_outline and extract_tables declare an output schema and return structuredContent next to the JSON text they always returned, so older clients see no change.

---

💡 Usage

With Claude Code

Register the server from the terminal:

claude mcp add docs -e DOCS_MCP_DIR=/path/to/your/documents -- go-docs-mcp

Or add it to the .mcp.json of the project you want it in:

{

"mcpServers": { "docs": { "command": "go-docs-mcp", "env": { "DOCS_MCP_DIR": "/path/to/your/documents" } } } }

With Claude Desktop

Claude Desktop needs the full path of the binary, and finds poppler, tesseract and pandoc only in some folders. The config and what to do when they are elsewhere are in doc/install.md.

With any MCP client

The server communicates over stdio using JSON-RPC 2.0:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | go-docs-mcp

---

📖 Tool Reference

list_documents

Lists all documents in the configured directory with format detection.

Parameters: None

Example output:

[

{ "filename": "architecture-guide.pdf", "title": "architecture-guide", "type": "pdf", "pages": 42, "size_bytes": 1048576 }, { "filename": "notes.md", "title": "notes", "type": "markdown", "pages": 0, "size_bytes": 4096 }, { "filename": "receipt.png", "title": "receipt", "type": "image", "pages": 0, "size_bytes": 220144 } ]

---

list_formats

Lists all supported document formats and their dependency status.

Parameters: None

---

read_document

Reads the extracted text content of a document. Automatically falls back to OCR if the document is image-based/scanned and pdftotext returns empty text.

Long texts come in pages. A page that does not reach the end finishes with [truncated: showing chars 0-50000 of 123456; call again with offset=50000], and the structured result carries text, next_offset (absent on the last page) and total_chars. Offsets count characters, not bytes.

Parameters:

convert_to_markdown and ocr_document take the same two parameters.

Example input:

{

"filename": "architecture-guide.pdf", "pages": "1-3,10-12" }

---

search_document

Searches within a document for lines matching a query. Returns matches with 2 lines of context and approximate page numbers.

Parameters:

Example output:

Found 3 matches for 'microservice' in architecture-guide.pdf:

--- Match 1 (page ~2, line 45) --- The system is composed of several

microservice components that communicate

via gRPC and message queues.

---

get_document_summary

Returns the text from the first 3 pages of a document as a quick summary.

Parameters:

---

get_document_metadata

Returns full document metadata.

Parameters:

Example output:

{

"title": "Architecture Guide", "author": "Jane Doe", "subject": "System Design", "creator": "LaTeX", "producer": "pdfTeX", "creation_date": "Thu May 15 10:30:00 2025", "modification_date": "Thu May 15 10:30:00 2025", "pages": 42, "file_size_bytes": 1048576, "pdf_version": "1.5" }

---

get_document_outline

Extracts the heading structure of a document as a structured list. For PDFs the outline is deduced from the extracted text (short lines that look like headings), not read from the PDF bookmarks; for Markdown and text files it comes from # headings.

Parameters:

---

extract_tables

Extracts tables from a document as structured data.

Parameters:

---

extract_images

Extracts the images of a PDF and returns each one as MCP image content (image/png), so clients that render images show them. Alpha masks and stencil masks are skipped, images are scaled down to 1600 px on the longer side, an image still over 4 MB after scaling is shrunk until it fits, and the images of one answer stay under 8 MB. A text item before the images describes them and says why any was left out.

Parameters: