nextcloud-mcp-server/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 (for OAuth setup) - Required to install OIDC app

Installation Methods

Choose one of the following installation methods:

• Using uv (Recommended)
• Using pip
• Using Docker
• From Source

---

Using uv (Recommended)

uv is a fast Python package installer and resolver.

Install uv

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

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

Install Nextcloud MCP Server

# Install from PyPI
uv pip install nextcloud-mcp-server

# Or install directly using uvx
uvx nextcloud-mcp-server --help

Verify Installation

uv run nextcloud-mcp-server --help

---

Using pip

Standard installation using pip:

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

# Install from PyPI
pip install nextcloud-mcp-server

# Verify installation
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

---

From Source

Install from the GitHub repository:

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
nextcloud-mcp-server --help

---

Next Steps

After installation:

1. Configure the server - See Configuration Guide
2. Set up authentication - See OAuth Setup Guide or Authentication
3. Run the server - See Running the Server

Updating

Update with uv

uv pip install --upgrade nextcloud-mcp-server

Update with pip

pip install --upgrade nextcloud-mcp-server

Update Docker Image

docker pull ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
docker-compose up -d  # Restart with new image

Update from Source

cd nextcloud-mcp-server
git pull origin master
uv sync  # or: pip install -e .

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
• OAuth Setup Guide - OAuth authentication setup
• Running the Server - Starting and managing the server