Installation¶

stirlingpdf-agent is a standard Python package and a prebuilt container image. Pick the path that matches how you want to run it.

Requirements¶

Python 3.11 – 3.14.
A reachable Stirling PDF service — see Backing Platform to deploy one locally.

From PyPI (recommended)¶

pip install stirlingpdf-agent

The base install includes the FastMCP MCP-server runtime (agent-utilities[mcp]), so the stirlingpdf-mcp console script is ready immediately.

Optional extras¶

Install an extra for additional capabilities:

Extra	Install	Pulls in
`agent`	`pip install "stirlingpdf-agent[agent]"`	Pydantic-AI agent server + Logfire tracing (`agent-utilities[agent,logfire]`)
`all`	`pip install "stirlingpdf-agent[all]"`	The MCP runtime, the agent server, and Logfire tracing
`test`	`pip install "stirlingpdf-agent[test]"`	`pytest`, `pytest-asyncio`, `pytest-cov`, `pytest-xdist`

# Typical: run both the MCP server and the A2A agent
pip install "stirlingpdf-agent[all]"

From source¶

git clone https://github.com/Knuckles-Team/stirlingpdf-agent.git
cd stirlingpdf-agent
pip install -e ".[all]"          # editable install with every extra

With uv:

uv pip install -e ".[all]"
uv run stirlingpdf-mcp

Prebuilt Docker image¶

A multi-stage, slim image is published on every release (entrypoint stirlingpdf-mcp):

docker pull knucklessg1/stirlingpdf-agent:latest

docker run --rm -i \
  -e STIRLINGPDF_URL=http://your-stirlingpdf:8080 \
  -e STIRLINGPDF_API_KEY=your_token \
  knucklessg1/stirlingpdf-agent:latest        # stdio transport (default)

For an HTTP server with a published port and the agent server, see Deployment.

Verify the install¶

stirlingpdf-mcp --help
python -c "import stirlingpdf_agent; print('stirlingpdf-agent import OK')"

Next steps¶

Deployment — run it as a long-lived MCP and agent server behind Caddy + DNS.
Usage — call the tools, the API, and the CLI.
Configuration — every environment variable.