admin/mcp-nextcloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ed5663747e4e3b56546041370586a0a9e923e771
mcp-nextcloud/docs/installation.md
T
Chris CoutinhoandClaude Opus 4.7 e2955e8246 fix(auth): address PR #758 round-5 medium/low review 
Three findings from the latest review on #758 (1 medium, 2 low):

Medium:
- browser_oauth_routes.oauth_logout: move delete_browser_session into a
  finally block so an error from delete_refresh_token can no longer leave
  an orphan browser_sessions row. The orphan was not exploitable
  (SessionAuthBackend rejects sessions without a live refresh token), but
  it lingered until the hourly cleanup cron — a correctness gap. New
  regression test pins the fix.

Low:
- oauth_callback_nextcloud: drop redundant ``or None`` from
  ``expected_nonce=nonce``. ``nonce`` is already ``str | None`` and
  ``secrets.token_urlsafe`` never produces an empty string, so the
  coercion was a no-op that could mislead future readers into thinking
  empty-string was a valid skip-the-check path.
- storage.RefreshTokenStorage.initialize: fail fast at startup when
  SQLite < 3.35, since ``DELETE ... RETURNING`` (used in
  ``delete_browser_session``) needs that minimum. Ubuntu 20.04 ships
  3.31 and would otherwise hit OperationalError on every logout.
  Prerequisite also documented in docs/installation.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-03 01:37:38 +02:00

4.6 KiB
Raw Blame History

Installation

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

Prerequisites

  • Python 3.11+ - Check with python3 --version
  • SQLite 3.35+ - Check with python3 -c "import sqlite3; print(sqlite3.sqlite_version)". The OAuth session storage uses DELETE ... RETURNING, which is only available from SQLite 3.35 (March 2021). Ubuntu 20.04 ships SQLite 3.31 and is not supported; upgrade the host or run from the Docker image, which bundles a newer libsqlite3.
  • 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)

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

Reference in New Issue View Git Blame Copy Permalink