SkillAgentSearch skills...

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-mcp

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

70/100

Supported Platforms

Claude Code
Claude Desktop
Cursor

Tags

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.

Substance
30/30
Structure
20/20
Description
12/15
Adoption
3/20
Freshness
5/15

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 found

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.

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.

SkillScoreStarsUpdatedFormat
document-reader-mcp (this skill)by ifmelate70313mo agoMCP Server
Agent-Reachby Panniantong100113.3k12d agoCLAUDE.md
hyperframesby heygen-com10087.1ktodayCLAUDE.md
rufloby ruvnet10082.1ktodayCLAUDE.md
headroomby headroomlabs-ai10080.2ktodayCLAUDE.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.

document-reader-mcp

License: MIT Python 3.10+ Version Platform

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.json or 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 YourUsername with your actual Windows username
  • Ensure the python command points to your Python 3.10+ installation (check with python --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/documents with the directory containing files you want to process
  • The -v flag mounts your documents directory as /documents in the container (read-only)
  • Use -i for interactive mode (required for stdio communication)
  • Use --rm to automatically remove the container after it stops
  • File paths in MCP tool calls should use /documents/filename.pdf format

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 document
  • max_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 document
  • max_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 convert
  • output_dir (string, optional): Directory where the markdown file and images will be saved. If not specified, saves in the same directory as the source file
  • output_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 extracted
  • markdown_preview: First 500 characters preview (truncated for AI context protection)
  • file_size_chars: Total character count of the saved markdown file
  • status: "success" or error status
  • message: 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

View on GitHub
GitHub Stars3
CategoryData
Updated1y ago
Forks1

Languages

Python

Trust signals

75/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium2 low