brandon/nextcloud-mcp-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
feature/update-plotly
nextcloud-mcp-server/docs/running.md
T
Chris Coutinho 9ef9fff2b0 docs: Update Docs
2025-10-14 01:23:38 +02:00

9.1 KiB
Raw Permalink Blame History

Running the Server

This guide covers different ways to start and run the Nextcloud MCP server.

Prerequisites

Before running the server:

  1. Install the server - See Installation Guide
  2. Configure environment - See Configuration Guide
  3. Set up authentication - See OAuth Setup or Authentication

Quick Start

Load your environment variables and start the server:

# Load environment variables from .env
export $(grep -v '^#' .env | xargs)

# Start the server
uv run nextcloud-mcp-server

The server will start on http://127.0.0.1:8000 by default.

Running Locally

Method 1: Using nextcloud-mcp-server CLI (Recommended)

The CLI provides a simple interface with built-in defaults:

OAuth Mode

# Auto-detected when NEXTCLOUD_USERNAME/PASSWORD not set
uv run nextcloud-mcp-server

# Explicitly force OAuth mode
uv run nextcloud-mcp-server --oauth

# OAuth with custom host and port
uv run nextcloud-mcp-server --oauth --host 0.0.0.0 --port 8080

# OAuth with pre-configured client
uv run nextcloud-mcp-server --oauth \
  --oauth-client-id abc123 \
  --oauth-client-secret xyz789

# OAuth with specific apps only
uv run nextcloud-mcp-server --oauth \
  --enable-app notes \
  --enable-app calendar

BasicAuth Mode (Legacy)

# Auto-detected when NEXTCLOUD_USERNAME/PASSWORD are set
uv run nextcloud-mcp-server

# Explicitly force BasicAuth mode
uv run nextcloud-mcp-server --no-oauth

# BasicAuth with specific apps
uv run nextcloud-mcp-server --no-oauth \
  --enable-app notes \
  --enable-app webdav

Method 2: Using uvicorn

For more control over server options (workers, reload, etc.):

# Load environment variables
export $(grep -v '^#' .env | xargs)

# Run with uvicorn
uv run uvicorn nextcloud_mcp_server.app:get_app \
  --factory \
  --host 127.0.0.1 \
  --port 8000 \
  --reload  # Enable auto-reload for development

See all uvicorn options at https://www.uvicorn.org/settings/

Method 3: Using Python Module

# Load environment variables
export $(grep -v '^#' .env | xargs)

# Run as Python module
python -m nextcloud_mcp_server.app --oauth --port 8000

Running with Docker

Basic Docker Run

# OAuth mode
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth

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

Docker with Persistent OAuth Storage

docker run -p 127.0.0.1:8000:8000 --env-file .env \
  -v $(pwd)/.oauth:/app/.oauth \
  --rm ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth

Docker Compose

Create docker-compose.yml:

version: '3.8'

services:
  mcp:
    image: ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
    command: --oauth --enable-app notes --enable-app calendar
    ports:
      - "127.0.0.1:8000:8000"
    env_file:
      - .env
    volumes:
      - ./oauth-storage:/app/.oauth
    restart: unless-stopped

Start the service:

# Start in foreground
docker-compose up

# Start in background
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down

Server Options

Host and Port

# Bind to all interfaces (accessible from network)
uv run nextcloud-mcp-server --host 0.0.0.0 --port 8000

# Bind to localhost only (default, more secure)
uv run nextcloud-mcp-server --host 127.0.0.1 --port 8000

# Use a different port
uv run nextcloud-mcp-server --port 8080

Security Note: Using --host 0.0.0.0 exposes the server to your network. Only use this if you understand the security implications.

Transport Protocols

The server supports multiple MCP transport protocols:

# Streamable HTTP (recommended)
uv run nextcloud-mcp-server --transport streamable-http

# SSE - Server-Sent Events (default, deprecated)
uv run nextcloud-mcp-server --transport sse

# HTTP
uv run nextcloud-mcp-server --transport http

Warning

SSE transport is deprecated and will be removed in a future version of the MCP spec. Please migrate to streamable-http.

Logging

# Set log level (critical, error, warning, info, debug, trace)
uv run nextcloud-mcp-server --log-level debug

# Production: use warning or error
uv run nextcloud-mcp-server --log-level warning

Selective App Enablement

By default, all supported Nextcloud apps are enabled. You can enable specific apps only:

# Available apps: notes, tables, webdav, calendar, contacts, deck

# Enable all apps (default)
uv run nextcloud-mcp-server

# Enable only Notes
uv run nextcloud-mcp-server --enable-app notes

# Enable multiple apps
uv run nextcloud-mcp-server \
  --enable-app notes \
  --enable-app calendar \
  --enable-app contacts

# Enable only WebDAV for file operations
uv run nextcloud-mcp-server --enable-app webdav

Use cases:

  • Reduce memory usage and startup time
  • Limit functionality for security/organizational reasons
  • Test specific app integrations
  • Run lightweight instances with only needed features

Development Mode

For active development with auto-reload:

# Using uvicorn with reload
uv run uvicorn nextcloud_mcp_server.app:get_app \
  --factory \
  --reload \
  --host 127.0.0.1 \
  --port 8000 \
  --log-level debug

Or use the CLI with reload flag:

uv run nextcloud-mcp-server --reload --log-level debug

Connecting to the Server

Using MCP Inspector

MCP Inspector is a browser-based tool for testing MCP servers:

# Start MCP Inspector
uv run mcp dev

# In the browser:
# 1. Enter server URL: http://localhost:8000
# 2. Complete OAuth flow (if using OAuth)
# 3. Explore tools and resources

Using MCP Clients

MCP clients (like Claude Desktop, LLM IDEs) can connect to your server:

  1. Configure the client with your server URL
  2. Complete OAuth authentication (if enabled)
  3. Start interacting with Nextcloud through the LLM

Verifying Server Status

Check Server Health

# Test if server is responding
curl http://localhost:8000/health

# Expected response: HTTP 200 OK

Check OAuth Configuration

Look for these log messages on startup:

OAuth mode:

INFO     OAuth mode detected (NEXTCLOUD_USERNAME/PASSWORD not set)
INFO     Configuring MCP server for OAuth mode
INFO     OIDC discovery successful
INFO     OAuth client ready: <client-id>...
INFO     OAuth initialization complete

BasicAuth mode:

INFO     BasicAuth mode detected (NEXTCLOUD_USERNAME/PASSWORD set)
INFO     Initializing Nextcloud client with BasicAuth

Process Management

Running as a Background Service

Using systemd (Linux)

Create /etc/systemd/system/nextcloud-mcp.service:

[Unit]
Description=Nextcloud MCP Server
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/nextcloud-mcp-server
EnvironmentFile=/path/to/.env
ExecStart=/path/to/uv run nextcloud-mcp-server --oauth
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable nextcloud-mcp
sudo systemctl start nextcloud-mcp
sudo systemctl status nextcloud-mcp

Using Docker Compose

See Docker Compose section above - includes restart: unless-stopped.

Monitoring Logs

# Local installation with systemd
sudo journalctl -u nextcloud-mcp -f

# Docker
docker logs -f <container-name>

# Docker Compose
docker-compose logs -f mcp

Performance Tuning

Multiple Workers

For production deployments with higher load:

# Using CLI (if supported)
uv run nextcloud-mcp-server --workers 4

# Using uvicorn
uv run uvicorn nextcloud_mcp_server.app:get_app \
  --factory \
  --workers 4 \
  --host 0.0.0.0 \
  --port 8000

Production Settings

# Recommended production configuration
uv run nextcloud-mcp-server \
  --oauth \
  --host 127.0.0.1 \
  --port 8000 \
  --log-level warning \
  --transport streamable-http \
  --workers 2

Troubleshooting

Server won't start

Check logs for errors:

uv run nextcloud-mcp-server --log-level debug

Common issues:

  • Environment variables not loaded - See Configuration
  • Port already in use - Try a different port with --port
  • OAuth configuration errors - See Troubleshooting

Can't connect to server

  1. Verify server is running: curl http://localhost:8000/health
  2. Check firewall settings
  3. Verify host binding (use 0.0.0.0 to allow network access)
  4. Check OAuth authentication if enabled

OAuth authentication fails

See Troubleshooting OAuth for detailed OAuth troubleshooting.

See Also

Reference in New Issue View Git Blame Copy Permalink