Document Understanding MCP Server

DOCUMENT_UNDERSTANDING_BASE_PATH (Environment Variable, Required): Specifies the absolute path to the directory the server is allowed to access for reading PDFs. The server will refuse to start if this is not set, unless --allow-any-path is used.
DOCUMENT_UNDERSTANDING_LOG_LEVEL (Environment Variable): Sets the minimum log level for console output (e.g., DEBUG, INFO, WARNING). Default=INFO.
DOCUMENT_UNDERSTANDING_LOG_FORMAT (Environment Variable): Sets console log format (plain or json). Default=plain.
DOCUMENT_UNDERSTANDING_LOG_FILE (Environment Variable): If set, specifies a path to write structured JSON logs (e.g., .tmp/logs/server.log). Directory will be created. Default=Disabled.
DOCUMENT_UNDERSTANDING_LOG_FILE_LEVEL (Environment Variable): Minimum level for file logging (e.g., DEBUG, INFO). Default=INFO.
DOCUMENT_UNDERSTANDING_DEFAULT_LANG (Environment Variable): Sets the default OCR language (e.g., eng, fra). Defaults to eng if not set.
ENABLE_SAVE_IMAGES_TO_FILES (Environment Variable): When set to true, enables saving extracted images to files when using the extract_images tool with the output_directory parameter. Default=false.
SAFE_OUTPUT_DIRECTORIES (Environment Variable): Colon-separated list of directories where images can be saved when ENABLE_SAVE_IMAGES_TO_FILES=true but ALLOW_ANY_PATH=false. For example: /tmp:/var/output:/data/images.
Capability Override / Enable Flags (Command-line):
--allow-no-java: If the Java runtime (required for extract_tables) is not found, the server will normally exit. Use this flag to allow startup, but the extract_tables tool will be disabled.
--allow-no-tesseract: If the Tesseract executable (required for OCR fallback) is not found, the server will normally exit. Use this flag to allow startup, but OCR fallback in extract_pdf_contents will be disabled.
--enable-experimental: Enables experimental tools (like find_nearby_content) which are disabled by default.
--allow-any-path: (SECURITY RISK) If set, disables the PDF_SERVER_BASE_PATH restriction and allows the server to attempt reading files from any path provided in tool arguments. Use with extreme caution and only in trusted environments.

1. Clone the repository:

    git clone <repo-url>

    cd document-understanding-mcp-server

    

    pip install uv

    

    uv venv # Create .venv

uv pip sync pyproject.toml
uv pip install -e '.[dev,test]'

    

    export DOCUMENT_UNDERSTANDING_BASE_PATH=/path/to/your/pdf_working_directory

    

This server runs using the standard MCP stdio communication. There are multiple ways to run the server:
When the package is installed via pip, you can use the entry point directly:

source .venv/bin/activate

{
  "mcpServers": {
    "document-understanding": {
      "command": "/path/to/document-understanding-mcp-server",
      "args": [
        "--enable-experimental"
      ]
    }
  }
}

File Paths: Before processing a PDF, use get_pdf_working_directory to find the allowed directory. Ensure any pdf_path arguments you provide refer to files within that directory (or subdirectories). Path traversal attempts (../) or absolute paths outside the working directory will be rejected unless the server was unsafely started with --allow-any-path.
Passwords: Currently, the server cannot handle password-protected PDFs for most tools (except table extraction). Processing encrypted files will likely fail. See docs/KNOWN_ISSUES.md.
Tool Availability: The list of available tools might change depending on the server's environment (e.g., if Java is missing and --allow-no-java was used, extract_tables will not be listed). Rely on the response from list_tools to know what is currently usable.
Use specific tools: Prefer search_pdf_text over extracting all content if you only need specific occurrences. Use extract_pdf_metadata if only metadata is needed.
Handle JSON: Expect JSON responses. Parse the text field of the ToolResponseContent as JSON.
Check status: Always check the status field in the JSON response. If it's "error", use the message and error_code fields for diagnostics (Note: errors are typically raised as exceptions by the server, the MCP client translates these).
Layout Information: The extract_pdf_layout tool provides rich structural information (text coordinates, drawings, image locations). This can be used for complex analysis (e.g., with find_nearby_content) but generates large responses.
Page Specification: Use the pages parameter effectively (e.g., "1-3, 5, -1") to limit processing when needed.
OCR Language: If processing non-English documents, specify the language(s) using ocr_language (e.g., "fra+eng" for French and English) for better accuracy.
Error Handling: Be prepared for FileNotFoundError if the pdf_path is incorrect, or ValueError for invalid page specifications or processing issues. Encrypted files may cause various errors. The server raises exceptions which the MCP client should surface.

1. Extracting French Text from Scanned Pages 2 & 3:
get_pdf_working_directory -> Check response for working_directory.
(LLM/User ensures mydoc.pdf is in the working directory)
extract_pdf_contents with pdf_path="mydoc.pdf", pages="2-3", ocr_language="fra".
Parse response, process text from the pages list.

2. Finding Text near an Image:
get_pdf_working_directory -> Get working_directory.
(LLM/User places report.pdf)
extract_pdf_layout with pdf_path="report.pdf", pages="5" (assuming image is on page 5).
Parse layout response. Identify the desired image based on xref, size, or rough bbox.
find_nearby_content (if enabled) with pdf_path="report.pdf", pages="5", target_bbox set to the image's bbox, content_type="text_block", direction="below" (e.g., to find caption).
Parse nearby response for the caption text.

3. Extracting Specific Tables after Metadata Check:
get_pdf_working_directory -> Get working_directory.
(LLM/User places data.pdf)
extract_pdf_metadata with pdf_path="data.pdf".
Check response: confirm page_count, look at metadata fields.
extract_tables with pdf_path="data.pdf", pages="2, 4" (e.g., only pages 2 and 4).
Parse response.