Backing Platform — Stirling PDF

stirlingpdf-agent is a client of a Stirling PDF service. This page provides a Docker recipe for deploying one locally to serve as the target of STIRLINGPDF_URL. For production topologies, follow the upstream Stirling PDF documentation.

Backing-system recipe

Each connector in the ecosystem follows the same convention — a docs/platform.md recipe for the system it integrates with, accompanied by a sample Compose stack that mirrors services/. Systems offered only as a managed service have no local recipe.

Single-node deployment (Compose)

Stirling PDF publishes an official image. The following stack runs one instance on :8080:

# docker/stirling-pdf.compose.yml
services:
  stirling-pdf:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    hostname: stirling-pdf
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - DISABLE_ADDITIONAL_FEATURES=false
      - LANGS=en_GB
    volumes:
      - training_data:/usr/share/tessdata
      - extra_configs:/configs
      - custom_files:/customFiles/
      - logs:/logs/
      - pipeline:/pipeline/
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8080/api/v1/info/status"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 40s

volumes:
  training_data:
  extra_configs:
  custom_files:
  logs:
  pipeline:

docker compose -f docker/stirling-pdf.compose.yml up -d

# Wait for the service to answer
curl -fsS http://localhost:8080/api/v1/info/status

Connect stirlingpdf-agent

export STIRLINGPDF_URL=http://localhost:8080
export STIRLINGPDF_API_KEY=your_token          # if the service requires one
export STIRLINGPDF_AGENT_VERIFY=True

stirlingpdf-mcp --transport streamable-http --host 0.0.0.0 --port 8000

Combined deployment

A combined stack places Stirling PDF and the MCP server on one Docker network, so the server reaches the service by container name:

# docker/stack.compose.yml
services:
  stirling-pdf:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
    hostname: stirling-pdf
    ports: ["8080:8080"]
    environment:
      - DISABLE_ADDITIONAL_FEATURES=false
      - LANGS=en_GB

  stirlingpdf-agent-mcp:
    image: knucklessg1/stirlingpdf-agent:latest
    depends_on: [stirling-pdf]
    environment:
      - STIRLINGPDF_URL=http://stirling-pdf:8080
      - STIRLINGPDF_AGENT_VERIFY=True
      - TRANSPORT=streamable-http
      - HOST=0.0.0.0
      - PORT=8000
    ports: ["8000:8000"]

docker compose -f docker/stack.compose.yml up -d

With the service running, the MCP tools and the StirlingPdfApi client operate against it directly.