Installation¶

nextcloud-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 Nextcloud instance with a user and an app password — see Backing Platform to deploy one locally.

From PyPI (recommended)¶

pip install nextcloud-agent

The base install pulls in agent-utilities[agent,logfire], so both the MCP server (nextcloud-mcp) and the graph agent (nextcloud-agent) are available immediately.

Optional extras¶

Extra	Install	Pulls in
(base)	`pip install nextcloud-agent`	MCP server + agent runtime via `agent-utilities[agent,logfire]`
`test`	`pip install "nextcloud-agent[test]"`	`pytest`, `pytest-asyncio`, `pytest-cov`, `pytest-xdist` for the test suite

# Typical: run the MCP server and the agent
pip install nextcloud-agent

From source¶

git clone https://github.com/Knuckles-Team/nextcloud-agent.git
cd nextcloud-agent
pip install -e ".[test]"          # editable install with the test extra

With uv:

uv pip install -e ".[test]"
uv run nextcloud-mcp

Prebuilt Docker image¶

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

docker pull knucklessg1/nextcloud-agent:latest

docker run --rm -i \
  -e NEXTCLOUD_URL=https://nextcloud.example.com \
  -e NEXTCLOUD_USERNAME=your-user \
  -e NEXTCLOUD_PASSWORD=your-app-password \
  knucklessg1/nextcloud-agent:latest        # stdio transport (default)

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

Verify the install¶

nextcloud-mcp --help
nextcloud-agent --help
python -c "import nextcloud_agent; print('nextcloud-agent ready')"

Next steps¶

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