mcp-nextcloud/docs/installation.md

Installation

This guide covers installing the Nextcloud MCP server on your system.

Prerequisites

• Python 3.11+ - Check with python3 --version
• Access to a Nextcloud instance - Self-hosted or cloud-hosted
• Administrator access (optional) - Only needed to customise app-password policies in Nextcloud settings; not required for any deployment mode (single-user, multi-user BasicAuth, or Login Flow v2)

Installation Methods

Choose one of the following installation methods:

• From Source (Recommended)
• Using Docker

---

From Source (Recommended)

Install from the GitHub repository using uv or pip.

Prerequisites

Install uv (recommended) or ensure pip is available:

# Install uv (recommended)
# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Clone the Repository

git clone https://github.com/cbcoutinho/nextcloud-mcp-server.git
cd nextcloud-mcp-server

Install Dependencies

Using uv (Recommended)

# Install dependencies
uv sync

# Install development dependencies (optional)
uv sync --group dev

Using pip

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

# Install development dependencies (optional)
pip install -e ".[dev]"

Verify Installation

# With uv
uv run nextcloud-mcp-server --help

# With pip/venv
nextcloud-mcp-server --help

---

Using Docker

A pre-built Docker image is available for easy deployment.

Pull the Image

docker pull ghcr.io/cbcoutinho/nextcloud-mcp-server:latest

Run the Container

# Prepare your .env file first (see Configuration guide)

# Run with environment file
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest

Docker Compose

Create a docker-compose.yml:

version: '3.8'

services:
  mcp:
    image: ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
    ports:
      - "127.0.0.1:8000:8000"
    env_file:
      - .env
    volumes:
      # For persistent OAuth client storage
      - ./oauth-storage:/app/.oauth
    restart: unless-stopped

Start the service:

docker-compose up -d

---

Next Steps

After installation:

1. Configure the server - See Configuration Guide
2. Set up authentication - See Authentication (multi-user deployments: see Login Flow v2)
3. Run the server - See Running the Server

Updating

Update from Source

cd nextcloud-mcp-server
git pull origin master

# Using uv
uv sync

# Or using pip
pip install -e .

Update Docker Image

docker pull ghcr.io/cbcoutinho/nextcloud-mcp-server:latest

# If using docker-compose
docker-compose up -d  # Restart with new image

# If using docker run
# Stop the old container and start a new one with the updated image

Troubleshooting Installation

Issue: "Python version too old"

Cause: Python 3.11+ is required.

Solution:

# Check your Python version
python3 --version

# Install Python 3.11+ from:
# - https://www.python.org/downloads/
# - Or use your system package manager (apt, brew, etc.)

Issue: "Command not found: nextcloud-mcp-server"

Cause: The package is not in your PATH.

Solution:

# Ensure your virtual environment is activated
source venv/bin/activate

# Or use uv run
uv run nextcloud-mcp-server --help

# Or use python -m
python -m nextcloud_mcp_server.app --help

Issue: Docker permission denied

Cause: Docker requires elevated permissions.

Solution:

# Add your user to the docker group (Linux)
sudo usermod -aG docker $USER
# Log out and back in

# Or use sudo
sudo docker run ...

See Also

• Configuration Guide - Environment variables and settings
• Authentication - Authentication modes comparison
• Login Flow v2 - Recommended multi-user setup
• Running the Server - Starting and managing the server