Docling Granite MCP Server

This is an MCP (Model Context Protocol) server implemented using FastMCP. It processes PDF documents using Docling and enhances image extractions with description explanations using the IBM Granite Vision model.

Features

• Document Conversion: Converts PDFs to Markdown format.
• Granite Vision Descriptions: Analyzes images/charts in the PDF and generates text explanations using ibm-granite/granite-vision-3.3-2b VLM.
• Streaming & Non-Streaming Options: Supports streaming the Markdown output in chunks or returning it as a single block.
• Page Offset Range: Supports parsing a subset of pages (start_page to end_page).
• Secure File Handling: Receives the file content via base64, saves it to a unique temporary file (timestamp_filename) inside the workspace temp_files/ directory, and clears it immediately after the conversion response is completed.
• Isolated Venv: Utilizes uv to manage python dependencies locally.

Setup

1. Virtual Environment: The project has been configured with an isolated Python virtual environment using uv inside this workspace folder.

2. Dependencies: The virtual environment contains:

   • fastmcp
   • docling[vlm] (includes PyTorch and IBM Granite vision pipeline components)
   • pypdfium2 (for determining PDF metadata/page counts)

How to Run

To run the MCP server with the HTTP SSE transport:

# Activate virtual environment and run
.venv/bin/python server.py

This runs the server at http://localhost:8000/sse.

Configuration for Claude Desktop / Cursor

You can add this server to your Claude Desktop configuration file (typically at ~/.config/Claude/claude_desktop_config.json) using the SSE transport settings:

{
  "mcpServers": {
    "docling-granite-mcp": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Running with Docker and Docker Compose

To containerize the MCP server and run it easily:

1. Build and Run via Docker Compose

We configure a persistent volume hf_cache to store Hugging Face weights so that the Granite Vision model does not need to be downloaded every time the container starts.

To build and start the server:

docker compose up --build

The server will be reachable at http://localhost:8000/sse on the host machine.

2. Configuration for Claude Desktop / Cursor (via Docker)

Once running via Docker Compose (or docker run), configure it in your Client Settings:

{
  "mcpServers": {
    "docling-granite-mcp-docker": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Tools Provided

convert_pdf

Converts a base64-encoded PDF to Markdown with Granite image descriptions.

• Arguments:
  • file_content_b64 (string, required): Base64-encoded string of the PDF content.
  • filename (string, required): Original filename (e.g., report.pdf).
  • stream (boolean, optional, default: false): If true, streams the output in chunks.
  • start_page (integer, optional, default: 1): Starting page index (1-based, inclusive).
  • end_page (integer, optional): Ending page index (1-based, inclusive).