Enables AI clients to read, search, and extract content from PDF, Office, EPUB, HTML, Jupyter notebooks, and images using OCR.
Also known as drolosoft/go-docs-mcp
- Stars
- 12
- Tools
- 13
- Downloads, 30 days
- —
- Latest version
- 1.5.0
- Last commit
- Nov 15, 2026
- License
- MIT
What is Go-Docs MCP?
Go-Docs enables AI clients to read, search, and extract content from PDF, Office, EPUB, HTML, Jupyter notebooks, and images using OCR. It exposes 13 tools, such as convert_to_markdown, extract_images, extract_tables.
Summary generated from the project's README
About Go-Docs MCP server
Go-Docs MCP is a single-binary tool designed for developers who need AI clients to interact with a wide variety of document formats. Unlike servers that focus on a single file type, this server handles 14 different formats including PDF, DOCX, XLSX, EPUB, Jupyter notebooks, and various image types. It operates locally by reading files from a specific directory configured via the DOCS_MCP_DIR environment variable, ensuring all data processing remains offline and secure.
Users can interact with their documents through 13 specialized tools. These include capabilities for full-text search, table extraction, and image extraction. For scanned documents or image files like PNG and JPG, the server utilizes OCR via Tesseract to extract text. It also supports fetching content from URLs with a 50MB limit. The server is highly portable, running on macOS, Linux, and Windows, and can be deployed via a simple Go install, Homebrew, or a Docker container.
Written from the project's README. Every use case is checked against a quote from it.
How to install Go-Docs MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Go-Docs MCP in Claude Code
$ claude mcp add --env 'DOCS_MCP_DIR=<DOCS_MCP_DIR>' go-docs-mcp -- docker run -i --rm ghcr.io/drolosoft/go-docs-mcp:1.5.0Install Go-Docs MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"go-docs-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/drolosoft/go-docs-mcp:1.5.0"
],
"env": {
"DOCS_MCP_DIR": "<DOCS_MCP_DIR>"
}
}
}
}Install Go-Docs MCP in VS Code
.vscode/mcp.json
{
"servers": {
"go-docs-mcp": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/drolosoft/go-docs-mcp:1.5.0"
],
"env": {
"DOCS_MCP_DIR": "<DOCS_MCP_DIR>"
}
}
}
}Install Go-Docs MCP in VS Code CLI
$ code --add-mcp '{"name":"go-docs-mcp","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/drolosoft/go-docs-mcp:1.5.0"],"env":{"DOCS_MCP_DIR":"<DOCS_MCP_DIR>"}}'Install Go-Docs MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"go-docs-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/drolosoft/go-docs-mcp:1.5.0"
],
"env": {
"DOCS_MCP_DIR": "<DOCS_MCP_DIR>"
}
}
}
}Install Go-Docs MCP in Codex
$ codex mcp add go-docs-mcp --env 'DOCS_MCP_DIR=<DOCS_MCP_DIR>' -- docker run -i --rm ghcr.io/drolosoft/go-docs-mcp:1.5.0Install Go-Docs MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.go-docs-mcp] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/drolosoft/go-docs-mcp:1.5.0"] [mcp_servers.go-docs-mcp.env] DOCS_MCP_DIR = "<DOCS_MCP_DIR>"
Install Go-Docs MCP in Gemini CLI
$ gemini mcp add -s user -e 'DOCS_MCP_DIR=<DOCS_MCP_DIR>' go-docs-mcp docker -- run -i --rm ghcr.io/drolosoft/go-docs-mcp:1.5.0Install Go-Docs MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"go-docs-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/drolosoft/go-docs-mcp:1.5.0"
],
"env": {
"DOCS_MCP_DIR": "<DOCS_MCP_DIR>"
}
}
}
}Go-Docs MCP tools 13
Read from the server with tools/listconvert_to_markdownRead-onlyConvert a document to clean Markdown format. Use this when you need structured, readable output from any document; for PDFs headings are detected and formatted, for TXT/CSV content is wrapped in code blocks, and MD files are returned as-is. Long output comes in pages of max_chars characters, like read_document. Read-only.
extract_imagesRead-onlyExtract the embedded images of a PDF as PNG image content, scaled to at most 1600 px on the longer side, 10 per call by default and 8 MB in total. Soft masks are not returned as images. Use this when you need to see figures, charts, or photos embedded in a PDF document. Read-only.
extract_tablesRead-onlyExtract table-like structures from a document, detecting pipe-delimited, tab-delimited, and multi-space-delimited columns. Use this when you need structured tabular data from a PDF, CSV, or text file. Read-only.
get_document_metadataRead-onlyGet document metadata including title, author, dates, page count, and file size. Use this when you need document properties without reading its content; returns full PDF-specific fields (subject, creator, producer, version) for PDF files. Read-only.
get_document_outlineRead-onlyExtract the heading structure and table of contents from a document. Use this to understand document organization before reading specific sections; detects numbered sections, ALL-CAPS headings, and markdown # headings. Read-only.
get_document_summaryRead-onlyGet a quick summary by extracting the first 3 pages or ~100 lines of a document. Use this to preview document content before deciding to read it in full. Read-only.
list_documentsRead-onlyList all documents in the configured directory with format detection and metadata (filename, pages, size). Use this to discover available documents before reading or searching. Read-only.
list_formatsRead-onlyShow all supported document formats and their dependency installation status. Use this to check which formats are available and diagnose missing dependencies. Read-only.
ocr_documentRead-onlyForce OCR text extraction on a PDF, bypassing normal text extraction. Use this when read_document returns garbled or empty text from a scanned PDF; requires tesseract and pdftoppm. Read-only.
read_documentRead-onlyRead text content from a document with optional page selection. Use this when you need the raw text of a PDF, TXT, MD, CSV, DOCX, XLSX, PPTX, ODT, EPUB, HTML, RTF or IPYNB file; TXT/MD/CSV are returned verbatim, the Office, EPUB, HTML, RTF and notebook formats via pandoc; PDFs support page ranges (e.g. "1-5", "1-3,7,10-12") and auto-OCR fallback for scanned pages. Long texts come in pages of max_chars characters; a truncated result ends with the offset to ask for next. Read-only.
read_imageRead-onlyExtract text from a standalone image file (PNG, JPG, WebP, TIFF, BMP) using OCR. Use this when you need to read text from an image rather than a document; supports multiple languages via tesseract. Read-only.
read_urlRead-onlyDownload a document from a URL and extract its text content (max 50MB). Use this when the document is hosted online rather than in the local directory; supports PDF and plain text URLs. Read-only, downloads to a temporary file.
Show all 13 toolsShow fewer tools
search_documentRead-onlySearch for text within a document and return matching lines with context and approximate page numbers. Use this when you need to find specific content without reading the entire document. Read-only.
Configuration
DOCS_MCP_DIRRequiredFolder with the documents to serve.
DOCS_MCP_DISABLE_URLtrue removes the read_url tool.
DOCS_MCP_OCR_LANGTesseract language for OCR, for example spa or eng+spa.
Automated checks
Ran Nov 16, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabledrolosoft/go-docs-mcp is public and reachablegithub.com/drolosoft/go-docs-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-15github.com/drolosoft/go-docs-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model13 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubInstall 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?
🏆 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 | Others | |
|---|---|---|
| Single binary, no runtime | Yes | Need Node/Python |
go install one-liner |
Yes | npm+deps or pip+venv |
| Multi-format (14 types) | Yes | One format each |
| Full-text search | Yes | Partial or none |
| OCR (scanned PDFs + images) | Yes | Rare |
| Image & table extraction | Yes | Partial |
| Document outline | Yes | Rare |
| Fetch from URL | Yes | Rare |
| Confined to one directory, read-only | Yes | Varies |
| Smart caching | Yes | No |
| Fully offline | Yes | Yes |
Go-Docs MCP reads them all from a single binary.
📋 Features: 13 Tools
| Category | Tool | Description |
|---|---|---|
| Discovery | list_documents |
List all documents with metadata (format, pages, size) |
| Discovery | list_formats |
List supported formats and dependency status |
| Reading | read_document |
Full text, specific page, or page ranges from any format |
| Reading | read_url |
Download from URL and extract text (50MB max) |
| Reading | get_document_summary |
First 3 pages as a quick overview |
| Search | search_document |
Case-insensitive full-text search with context |
| Analysis | get_document_metadata |
Title, author, dates, version, page count |
| Analysis | get_document_outline |
Heading structure deduced from the text |
| Analysis | extract_tables |
Tables as structured data |
| Analysis | extract_images |
Images as PNG image content, scaled to fit (max 10 per call, 8 MB budget) |
| OCR | ocr_document |
Force OCR on scanned/image-based PDFs |
| OCR | read_image |
Extract text from PNG, JPG, WebP, TIFF, BMP via OCR |
| Export | convert_to_markdown |
Convert any document to clean Markdown |
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:
offsetandmax_charson 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.
🚀 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_<version>.mcpbfrom 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.
⚙️ 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://<filename> (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:
| Name | Type | Required | Description |
|---|---|---|---|
filename |
string | Yes | The document filename to read |
page |
number | No | Single page number (1-based). Omit for full text. |
pages |
string | No | Page ranges, e.g. "1-5", "10", "1-3,7,10-12". Overrides page. |
offset |
number | No | Character offset to start from (default 0). |
max_chars |
number | No | Characters to return (default 50000, at most 200000). |
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:
| Name | Type | Required | Description |
|---|---|---|---|
filename |
string | Yes | The document filename to search |
query |
string | Yes | Search query (case-insensitive) |
max_results |
number | No | Matches to show (default 50, at most 500). The header still counts all of them. |
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:
| Name | Type | Required | Description |
|---|---|---|---|
filename |
string | Yes | The document filename to summarize |
get_document_metadata
Returns full document metadata.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
filename |
string | Yes | The document filename to get metadata for |
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:
| Name | Type | Required | Description |
|---|---|---|---|
filename |
string | Yes | The document filename to extract outline from |
extract_tables
Extracts tables from a document as structured data.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
filename |
string | Yes | The document filename to extract tables from |
page |
number | No | Specific page to extract from. Omit for all pages. |
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:
| Name | Type | Required | Description |
|---|---|---|---|
filename |
string | Yes | The document filename to extract images from |
page |
number | No | Specific page to extract from. Omit for all pages. |
max_images |
number | No | Images to return (default 10, at most 50). |
Example output: a text item that describes the images, then one image/png item per image.
{
"images": [
{
"page": 1,
"index": 0,
"format": "png",
"mime_type": "image/png",
"width": 1600,
"height": 1200,
"original_width": 2048,
"original_height": 1536
}
],
"found": 3,
"notes": ["returned the first 1 of 3 images; raise max_images or ask for one page to see the others"]
}
read_url
Downloads a document from a URL and extracts its text content. Accepts application/pdf and text/* responses, up to 50MB. Set DOCS_MCP_DISABLE_URL=1 to remove this tool entirely.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
url |
string | Yes | The URL of the document to download and read |
pages |
string | No | Page ranges to extract, e.g. "1-5". Omit for full text. |
Example input:
{
"url": "https://example.com/report.pdf",
"pages": "1-3"
}
ocr_document
Forces OCR on a PDF document using tesseract. Useful for scanned/image-based PDFs or when pdftotext returns garbled text. Requires tesseract and pdftoppm.
Note:
read_documentalready auto-detects image-based PDFs and falls back to OCR. Useocr_documentwhen you want to force OCR regardless, or need to specify a non-English language.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
filename |
string | Yes | The PDF filename to OCR |
page |
number | No | Specific page to OCR (1-based). Omit for all pages. |
language |
string | No | Tesseract language code (default: DOCS_MCP_OCR_LANG, then eng). Use spa, fra, etc. |
offset, max_chars |
number | No | Same paging as read_document. |
Example input:
{
"filename": "scanned-contract.pdf",
"page": 1,
"language": "spa"
}
read_image
Extracts text from an image file using OCR. Supports PNG, JPG, WebP, TIFF and BMP. Requires tesseract.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
filename |
string | Yes | The image filename to read (PNG, JPG, WebP, TIFF, BMP) |
language |
string | No | Tesseract language code (default: DOCS_MCP_OCR_LANG, then eng). |
Example input:
{
"filename": "receipt.png",
"language": "eng"
}
🔒 Security
- Confined to one directory: every file is resolved with its symlinks and must end up inside
DOCS_MCP_DIR. A symlink that points outside is not listed and cannot be read. Filenames with path separators or../are rejected before that. - Extension filter: only supported formats are served.
- Read-only: the server never writes inside
DOCS_MCP_DIR, and every tool is announced to clients as read-only, non-destructive and idempotent. - Timeouts on every external process: poppler, tesseract and pandoc run under a context deadline (60 s per extraction, 120 s per OCR page, 10 min per OCR call) and are killed when it passes. Page ranges are checked against the real page count and capped at 200 pages per call.
read_url: 60 s timeout, 50MB limit,application/pdfortext/*only, temp files removed right after reading. Hosts that resolve to private, loopback, link-local or cloud metadata addresses are refused, on the first request and on every redirect. SetDOCS_MCP_DISABLE_URL=1to drop the tool from the server if your documents may contain untrusted instructions. Environment proxies are ignored unlessDOCS_MCP_URL_PROXY=1, because behind a proxy the connect-time check would judge the proxy, not the target.- Bounded results: text tools return pages of at most 200,000 characters, search shows at most 500 matches and images stop at 8 MB per call; any tool result over 9 MB is replaced with an error. The text cache is capped by
DOCS_MCP_CACHE_MB. - Error messages carry file names, never absolute paths of the host.
How to report a problem is in SECURITY.md.
🛠️ Development
make build # Build the binary
make test # Run tests with race detector
make clean # Remove build artifacts
CI runs gofmt, vet, the race tests with poppler, tesseract and pandoc installed, and govulncheck on every push. A tag v* builds the release archives with goreleaser. See CONTRIBUTING.md.
How the binary serves both MCP protocol eras (the initialize handshake and the stateless 2026-07-28 revision) and how that is tested: doc/MCP-2026-07-28.md.
Project structure
go-docs-mcp/
main.go # MCP server setup, 13 tool registrations
resources.go # docs:// resources
internal/
pdf/
reader.go # Document extraction, caching, search, metadata, images, OCR
doc/
formats.md # What each format supports, limits of a call
install.md # Install paths, Claude Desktop, env vars
MCP-2026-07-28.md # Both protocol eras and how they are tested
WHY-MCP.md # Why an MCP server and not a direct tool
Makefile # Build targets
go.mod # Module definition
🦙 Glama Score
📄 License
MIT - Copyright 2026 Drolosoft
💛 Support
Drolosoft: Tools we wish existed
Go-Docs MCP questions
How do I add Go-Docs MCP to Claude Code?
Run claude mcp add --env 'DOCS_MCP_DIR=<DOCS_MCP_DIR>' go-docs-mcp -- docker run -i --rm ghcr.io/drolosoft/go-docs-mcp:1.5.0 in your terminal. Add --scope user to make it available in every project.
How do I add Go-Docs MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Go-Docs MCP provide?
It exposes 13 tools, including convert_to_markdown, extract_images, extract_tables, get_document_metadata, get_document_outline.
What file formats are supported?
The server supports 14 formats including PDF, TXT, MD, CSV, DOCX, XLSX, PPTX, ODT, EPUB, HTML, RTF, Jupyter notebooks, and various image types like PNG and JPG.
Can the server read scanned documents?
Yes, it uses OCR (specifically Tesseract) to extract text from scanned PDFs and images.
How do I install it using Go?
You can install it using the command: go install github.com/drolosoft/go-docs-mcp@latest
Does it work offline?
Yes, the server is designed to work fully offline.