pdf-lite-mcp

A simplified Python MCP server for reading PDF files, specifically optimized for Amazon Q CLI usage.

Built as a streamlined alternative to complex PDF processing tools, focusing on clean output and reliable performance.

Features

• Read PDFs from local files or URLs
• Extract specific pages or full content
• Metadata extraction (title, author, page count)
• Batch processing support
• Security-focused with path validation

Installation

From PyPI (recommended)

# Install using uvx (no need to clone repository)
uvx pdf-lite-mcp

# Or install globally
pip install pdf-lite-mcp

From source

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install
git clone https://github.com/tsaol/pdf-lite-mcp.git
cd pdf-lite-mcp
uv sync

Amazon Q CLI Configuration

Using PyPI package (recommended)

{
  "mcpServers": {
    "pdf-lite": {
      "command": "uvx",
      "args": ["pdf-lite-mcp"],
      "disabled": false,
      "autoApprove": ["read_pdf"]
    }
  }
}

Using local development version

{
  "mcpServers": {
    "pdf-lite": {
      "command": "uv",
      "args": ["run", "python", "src/main.py"],
      "cwd": "/path/to/pdf-lite-mcp",
      "env": {
        "PYTHONPATH": "."
      }
    }
  }
}

Using Git URL

{
  "mcpServers": {
    "pdf-lite": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/tsaol/pdf-lite-mcp.git", "pdf-lite-mcp"],
      "env": {
        "PYTHONPATH": "."
      }
    }
  }
}

Usage

Basic PDF Reading

{
  "tool_name": "read_pdf",
  "arguments": {
    "sources": [{"path": "./document.pdf"}],
    "include_full_text": true
  }
}

Specific Pages

{
  "tool_name": "read_pdf",
  "arguments": {
    "sources": [{"path": "./report.pdf", "pages": [1, 3, 5]}]
  }
}

Multiple PDFs

{
  "tool_name": "read_pdf",
  "arguments": {
    "sources": [
      {"path": "./doc1.pdf"},
      {"url": "https://example.com/doc2.pdf"}
    ]
  }
}

Testing

# Basic tests
uv run python tests/simple_test.py

# Server tests
uv run python tests/test_server.py

# PDF processing tests (requires network)
uv run python tests/test_with_pdf.py

License

MIT License - see LICENSE file for details.