document-reader-mcp
Universal MCP server for extracting text from various document formats and converts to .md file
Install / Use
claude mcp add ifmelate -- npx -y github:ifmelate/document-reader-mcpIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Data & AnalyticsSupported Platforms
Our assessment of document-reader-mcp
document-reader-mcp scores 70/100 on our quality scale, 552nd of 599 Data & Analytics skills we index.
Its MCP Server is 17 KB long, well organised into 64 sections with 24 code examples: a thorough specification that gives an agent plenty to work with.
It has 3 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated about 13 months ago. Expect some instructions to reference tool versions or APIs that have since changed.
- Our last check on 2026-09-23 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 75/100, with 3 cautions from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-06. Automated pattern scan on 2026-10-06. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
document-reader-mcp compared with similar skills
All 4 of these similar skills score higher than document-reader-mcp; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| document-reader-mcp (this skill)by ifmelate | 70 | 3 | 13mo ago | MCP Server |
| Agent-Reachby Panniantong | 100 | 113.3k | 12d ago | CLAUDE.md |
| hyperframesby heygen-com | 100 | 87.1k | today | CLAUDE.md |
| rufloby ruvnet | 100 | 82.1k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 80.2k | today | CLAUDE.md |
Frequently asked questions
- How do I install document-reader-mcp?
- Run
claude mcp add ifmelate -- npx -y github:ifmelate/document-reader-mcp. The install tabs above show the steps for each supported agent. - Which AI agents does document-reader-mcp work with?
- It is written for Claude Code, Claude Desktop and Cursor, as a MCP Server file. Other agents that read the same format can often use it too.
- Is document-reader-mcp safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 75/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is document-reader-mcp still maintained?
- The repository was last updated about 13 months ago. Expect some instructions to reference tool versions or APIs that have since changed.
Skill content
View source on GitHubdocument-reader-mcp
Universal MCP server for extracting text from various document formats. Supports streaming, page/row limits, encoding detection, and simple rate limiting.
Cross-platform compatible: Works seamlessly on macOS, Linux, and Windows with identical functionality.
Supported Formats
| Format | Extensions | Dependencies | Status |
|--------|-----------|--------------|--------|
| PDF | .pdf | pdfminer.six, pymupdf | ✅ Included (text + images) |
| Excel | .xlsx, .xlsm, .xltx, .xltm | openpyxl | ✅ Included |
| Word | .docx | python-docx | ✅ Included |
| CSV | .csv | Built-in | ✅ Always available |
| Plain Text | .txt, .log, .text | Built-in | ✅ Always available |
| JSON | .json | Built-in | ✅ Always available |
| Markdown | .md, .markdown | Built-in | ✅ Always available |
Features
✅ Cross-platform: Works on macOS, Linux, and Windows
✅ Multiple format support: PDF, Excel, CSV, TXT, JSON, Markdown, DOCX, PowerPoint, HTML
✅ Markdown conversion: Convert documents to Markdown with automatic image extraction
✅ PDF image extraction: Automatically extracts and embeds images from PDFs at appropriate page positions
✅ Streaming API: Memory-efficient processing of large files
✅ Smart encoding detection: Handles UTF-8, Latin-1, CP1252, ISO-8859-1
✅ Context-aware limits: Automatic truncation to prevent AI context overflow
✅ Rate limiting: Process-wide rate limiting (configurable)
✅ Docker support: Run in isolated container with non-root user
✅ Modular design: Easy to extend with new formats
✅ Minimal dependencies: Most formats use Python stdlib only
Installation
Option 1: Install from GitHub (Recommended)
macOS/Linux
# Clone the repository
git clone https://github.com/ifmelate/document-reader-mcp.git
cd document-reader-mcp
# Create virtual environment and install dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Windows (Command Prompt)
# Clone the repository
git clone https://github.com/ifmelate/document-reader-mcp.git
cd document-reader-mcp
# Create virtual environment and install dependencies
python -m venv .venv
.venv\Scripts\activate.bat
pip install -r requirements.txt
Windows (PowerShell)
# Clone the repository
git clone https://github.com/ifmelate/document-reader-mcp.git
cd document-reader-mcp
# Create virtual environment and install dependencies
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Note for Windows PowerShell users: If you encounter an execution policy error, run:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Quick Setup Scripts
For convenience, you can use the provided setup scripts:
macOS/Linux:
chmod +x dev-setup.sh
./dev-setup.sh
Windows (Command Prompt):
dev-setup.bat
Windows (PowerShell):
.\dev-setup.ps1
These scripts will create the virtual environment, install dependencies, and set up the development environment automatically.
Option 2: Direct Install with pip
pip install git+https://github.com/ifmelate/document-reader-mcp.git
Option 3: Docker
# Clone the repository
git clone https://github.com/ifmelate/document-reader-mcp.git
cd document-reader-mcp
# Build the Docker image
docker build -t document-reader-mcp:latest .
See Docker Configuration below for MCP client setup.
Running the Server
After installation, start the MCP server:
python -m server.main
The server runs over stdio for integration with MCP-compatible clients.
Configuration in Cursor (or other MCP clients)
For Cursor IDE
Add this configuration to your Cursor MCP settings:
- macOS/Linux:
~/.cursor/mcp.json - Windows:
%APPDATA%\Cursor\User\globalStorage\mcp.jsonor via Settings → MCP
macOS/Linux Configuration
{
"mcpServers": {
"document-reader": {
"command": "python3",
"args": ["-m", "server.main"],
"cwd": "/absolute/path/to/document-reader-mcp"
}
}
}
Windows Configuration
{
"mcpServers": {
"document-reader": {
"command": "python",
"args": ["-m", "server.main"],
"cwd": "C:\\Users\\YourUsername\\document-reader-mcp"
}
}
}
Important for Windows users:
- Use double backslashes (
\\) in JSON paths, or use forward slashes (/) which also work on Windows - Replace
YourUsernamewith your actual Windows username - Ensure the
pythoncommand points to your Python 3.10+ installation (check withpython --version)
For Claude Desktop or other MCP clients
Add similar configuration to your client's MCP settings file, adjusting the path accordingly.
Docker Configuration
To use the Docker version with MCP clients:
{
"mcpServers": {
"document-reader": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-v", "/absolute/path/to/documents:/documents:ro",
"document-reader-mcp:latest"
]
}
}
}
Important notes:
- Replace
/absolute/path/to/documentswith the directory containing files you want to process - The
-vflag mounts your documents directory as/documentsin the container (read-only) - Use
-ifor interactive mode (required for stdio communication) - Use
--rmto automatically remove the container after it stops - File paths in MCP tool calls should use
/documents/filename.pdfformat
Multiple volume mounts:
If you need to access files from multiple directories:
{
"mcpServers": {
"document-reader": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-v", "/Users/you/Documents:/documents:ro",
"-v", "/Users/you/Downloads:/downloads:ro",
"document-reader-mcp:latest"
]
}
}
}
Custom rate limiting:
{
"mcpServers": {
"document-reader": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "DOC_READER_RATE_LIMIT_PER_MINUTE=120",
"-v", "/absolute/path/to/documents:/documents:ro",
"document-reader-mcp:latest"
]
}
}
}
Security considerations for Docker:
- The container runs as non-root user (UID 1000)
- Volumes are mounted read-only (
:ro) for safety - No network ports are exposed
- Container has minimal attack surface
Available Tools
Once configured, you can use these tools:
Tool: extract_text_from_file
Extract complete text from a document file.
Parameters:
path(string, required): Absolute or relative path to the documentmax_pages(int, optional): For PDFs, parse only the first N pages (default: 50, set to 0 to disable)max_rows(int, optional): For CSV/Excel, parse only N data rows (default: 500, set to 0 to disable)
Returns: Extracted text as string (automatically truncated at 100,000 characters by default)
Supported formats: .pdf, .xlsx, .xlsm, .csv, .txt, .json, .md, .docx
Note: For large files, use extract_text_from_file_stream instead to avoid memory issues.
Default Limits: To prevent AI context overflow, the tool applies sensible defaults:
- PDFs: First 50 pages
- Excel/CSV: First 500 rows
- All formats: 100,000 character output limit
Tool: extract_text_from_file_stream
Stream text chunks from a document (memory-efficient for large files).
Parameters:
path(string, required): Absolute or relative path to the documentmax_pages(int, optional): For PDFs, page cap (default: 50, set to 0 to disable)max_rows(int, optional): For CSV/Excel, row cap (default: 500, set to 0 to disable)chunk_size(int, optional): Characters per chunk (default: 4096, min: 512)
Yields: Text chunks as strings
Supported formats: All formats from extract_text_from_file
Tool: convert_to_markdown
Convert various document formats to Markdown, extracting and saving images when applicable.
⚠️ Important: This tool converts the ENTIRE document and saves it to a file. It ignores the DOC_READER_DEFAULT_MAX_ROWS, DOC_READER_DEFAULT_MAX_PAGES, and DOC_READER_MAX_OUTPUT_CHARS environment variables. Only the preview returned to the AI is limited to protect context - the saved file contains the complete document.
Parameters:
path(string, required): Absolute or relative path to the file to convertoutput_dir(string, optional): Directory where the markdown file and images will be saved. If not specified, saves in the same directory as the source fileoutput_filename(string, optional): Name for the output markdown file (without extension). If not specified, uses the source filename with .md extension
Returns: Dictionary containing:
markdown_path: Path to the saved markdown file (contains FULL content, not truncated)images_dir: Path to the directory containing extracted images (if any)image_count: Number of images extractedmarkdown_preview: First 500 characters preview (truncated for AI context protection)file_size_chars: Total character count of the saved markdown filestatus: "success" or error statusmessage: Human-readable status message
Supported formats:
- PDF (
.pdf) - with automatic image extraction and positioning at page locations - Excel (
.xlsx,.xlsm,.xltx,.xltm) - converted to markdown tables - Word (
.docx) - with image extraction - CSV (
.csv) - converted to markdown tables - PowerPoint (
.pptx) - text and images - HTML (
.html,.htm) - Plain text (
.txt,.log) - Images (
.jpg,.jpeg,.png) - with OCR if available
Example Usage:
# Convert a Word document with images
result = convert_to_markdown(
path="/path/to/document.docx",
output_dir="/path/to/output"
)
# Creates: /path/to/output/document.md
# /path/to/output/document_images/image_1.png
# /path/to/output/document_images/image_2.png
Important Notes:
- Full file is saved: The complete markdown file is saved to disk without any truncation, regardless of size
- Preview is truncated: Only the preview returned to the AI is limited to 500 characters to protect context
- Images: Automatically extracted from supported formats and saved in a
{filename}_images/subdirectory, with markdown using relative paths to reference them - PDF images: Images are intelligently positioned throughout the markdown document at their corresponding page locations, making them viewable in preview
Usage Examples
In Cursor Chat:
Extract text from ~/Downloads/report.pdf and summarize the findings
Read the CSV file data.csv and show me the first 10 rows
What's in the JSON file config.json?
Convert the Word document ~/Documents/proposal.docx to Markdown and save it in ~/Documents/markdown/
Convert this Excel file to Markdown: ~/data/sales_report.xlsx
Programmatic Usage:
# Via MCP client - Extract text
result = await client.call_tool("extract_text_from_file", {
"path": "/path/to/document.pdf",
"max_pages": 5
})
# Streaming large files
async for chunk in client.stream_tool("extract_text_from_file_stream", {
"path": "/path/to/large_file.csv",
"chunk_
Truncated for display — read the full file on GitHub.
Related Skills
Agent-Reach
113.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
hyperframes
87.1kAI video you can actually edit. HyperFrames is a free, open-source AI video editor. Describe any video and get a real project you can change down to the frame.
ruflo
82.1k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
80.2kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
