Nextcloud MCP Server

# 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](installation.md) 2. **Configure environment** - See [Configuration Guide](configuration.md) 3. **Set up authentication** - See [OAuth Setup](oauth-setup.md) or [Authentication](authentication.md) --- ## Quick Start Load your environment variables and start the server: ```bash # 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 ```bash # 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) ```bash # 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.): ```bash # 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/](https://www.uvicorn.org/settings/) ### Method 3: Using Python Module ```bash # 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 ```bash # 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 ```bash 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`: ```yaml 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: ```bash # 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 ```bash # 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: ```bash # 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 ```bash # 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: ```bash # 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: ```bash # 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: ```bash 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: ```bash # 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 ```bash # 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`: ```ini [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: ```bash 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](#docker-compose) above - includes `restart: unless-stopped`. ### Monitoring Logs ```bash # 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: ```bash # 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 ```bash # 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: ```bash uv run nextcloud-mcp-server --log-level debug ``` Common issues: - Environment variables not loaded - See [Configuration](configuration.md#loading-environment-variables) - Port already in use - Try a different port with `--port` - OAuth configuration errors - See [Troubleshooting](troubleshooting.md) ### 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](troubleshooting.md) for detailed OAuth troubleshooting. --- ## See Also - [Configuration Guide](configuration.md) - Environment variables - [OAuth Setup](oauth-setup.md) - OAuth authentication setup - [Troubleshooting](troubleshooting.md) - Common issues and solutions - [Installation](installation.md) - Installing the server