brandon/nextcloud-mcp-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Update README and docs

Browse Source
This commit is contained in:
Chris Coutinho
2025-10-13 18:08:00 +02:00
parent a4a7fb48d6
commit 2489a714b8
5 changed files with 1183 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/authentication.md
+88
View File
@@ -0,0 +1,88 @@
# Authentication
The Nextcloud MCP server supports two authentication modes for connecting to your Nextcloud instance.
## Authentication Modes Comparison
| Mode | Status | Security | Use Case |
|------|--------|----------|----------|
| **OAuth2/OIDC** | ✅ Recommended | 🔒 High | Production deployments, multi-user scenarios |
| **Basic Auth** | ⚠️ Legacy | ⚠️ Lower | Development, backward compatibility |
## OAuth2/OIDC (Recommended)
OAuth2/OIDC authentication provides secure, token-based authentication following modern security standards.
### Benefits
- **Zero-config deployment** via dynamic client registration
- **No credential storage** in environment variables
- **Per-user authentication** with access tokens
- **Automatic token validation** via Nextcloud OIDC
- **Secure by design** following OAuth 2.0 standards
### Current Implementation Limitations
> [!IMPORTANT]
> - Only tested with Nextcloud `user_oidc` and `oidc` apps (Nextcloud as identity provider)
> - Requires a patch for Bearer token support on non-OCS endpoints (see [oauth2-bearer-token-session-issue.md](oauth2-bearer-token-session-issue.md))
> - External identity providers (Azure AD, Keycloak, etc.) have not been tested
> - Dynamic client registration credentials expire (default: 1 hour) - use pre-configured clients for production
### How OAuth Works
When a client connects to the MCP server with OAuth enabled:
1. Client receives OAuth authorization URL from the MCP server
2. User authenticates via browser to Nextcloud
3. Nextcloud redirects back with authorization code
4. Client exchanges code for access token
5. Client uses token to access MCP server
All API requests to Nextcloud use the user's OAuth token, ensuring proper permissions and audit trails.
### See Also
- [OAuth Setup Guide](oauth-setup.md) - Step-by-step setup instructions
- [Configuration](configuration.md) - Environment variables
- [Troubleshooting](troubleshooting.md) - Common OAuth issues
## Basic Authentication (Legacy)
Basic Authentication uses username and password credentials directly.
### Benefits
- **Simple setup** with username/password
- **Single-user** server instances
- **Quick for development** and testing
### Limitations
- **Credentials in environment** (less secure)
- **Single user only** - all requests use the same account
- **No audit trail** - all actions appear from the same user
- **Maintained for compatibility** - will be deprecated in future versions
> [!WARNING]
> **Security Notice:** Basic Authentication stores credentials in environment variables and is less secure than OAuth. It's maintained for backward compatibility only and may be deprecated in future versions. Use OAuth for production deployments.
### See Also
- [Configuration](configuration.md#basic-authentication-legacy) - BasicAuth environment variables
- [Running the Server](running.md#basicauth-mode-legacy) - BasicAuth examples
## Mode Detection
The server automatically detects the authentication mode:
- **OAuth mode**: When `NEXTCLOUD_USERNAME` and `NEXTCLOUD_PASSWORD` are NOT set
- **BasicAuth mode**: When both username and password are provided
You can also force a specific mode using CLI flags:
```bash
# Force OAuth mode
uv run nextcloud-mcp-server --oauth
# Force BasicAuth mode
uv run nextcloud-mcp-server --no-oauth
```
## Switching Between Modes
See [Troubleshooting: Switching Between OAuth and BasicAuth](troubleshooting.md#switching-between-oauth-and-basicauth) for instructions.
docs/configuration.md
+243
View File
@@ -0,0 +1,243 @@
# Configuration
The Nextcloud MCP server requires configuration to connect to your Nextcloud instance. Configuration is provided through environment variables, typically stored in a `.env` file.
## Quick Start
Create a `.env` file based on `env.sample`:
```bash
cp env.sample .env
# Edit .env with your Nextcloud details
```
Then choose your authentication mode:
- [OAuth2/OIDC Configuration](#oauth2oidc-configuration) (Recommended)
- [Basic Authentication Configuration](#basic-authentication-legacy)
---
## OAuth2/OIDC Configuration
OAuth2/OIDC is the recommended authentication mode for production deployments.
### Minimal Configuration (Auto-registration)
```dotenv
# .env file for OAuth with auto-registration
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
# Leave these EMPTY for OAuth mode
NEXTCLOUD_USERNAME=
NEXTCLOUD_PASSWORD=
```
This minimal configuration uses dynamic client registration to automatically register an OAuth client at startup.
### Full Configuration (Pre-configured Client)
```dotenv
# .env file for OAuth with pre-configured client
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
# OAuth Client Credentials (optional - auto-registers if not provided)
NEXTCLOUD_OIDC_CLIENT_ID=your-client-id
NEXTCLOUD_OIDC_CLIENT_SECRET=your-client-secret
# OAuth Storage and Callback Settings (optional)
NEXTCLOUD_OIDC_CLIENT_STORAGE=.nextcloud_oauth_client.json
NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
# Leave these EMPTY for OAuth mode
NEXTCLOUD_USERNAME=
NEXTCLOUD_PASSWORD=
```
### Environment Variables Reference
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `NEXTCLOUD_HOST` | ✅ Yes | - | Full URL of your Nextcloud instance (e.g., `https://cloud.example.com`) |
| `NEXTCLOUD_OIDC_CLIENT_ID` | ⚠️ Optional | - | OAuth client ID (auto-registers if empty) |
| `NEXTCLOUD_OIDC_CLIENT_SECRET` | ⚠️ Optional | - | OAuth client secret (auto-registers if empty) |
| `NEXTCLOUD_OIDC_CLIENT_STORAGE` | ⚠️ Optional | `.nextcloud_oauth_client.json` | Path to store auto-registered client credentials |
| `NEXTCLOUD_MCP_SERVER_URL` | ⚠️ Optional | `http://localhost:8000` | MCP server URL for OAuth callbacks |
| `NEXTCLOUD_USERNAME` | ❌ Must be empty | - | Leave empty to enable OAuth mode |
| `NEXTCLOUD_PASSWORD` | ❌ Must be empty | - | Leave empty to enable OAuth mode |
### Prerequisites
Before using OAuth configuration:
1. **Install Nextcloud OIDC app** - Navigate to Apps → Security in your Nextcloud instance
2. **Enable dynamic client registration** (if using auto-registration) - Settings → OIDC
3. **Apply Bearer token patch** (if using non-OCS endpoints) - See [oauth2-bearer-token-session-issue.md](oauth2-bearer-token-session-issue.md)
See the [OAuth Setup Guide](oauth-setup.md) for detailed instructions.
---
## Basic Authentication (Legacy)
Basic Authentication is maintained for backward compatibility. It uses username and password credentials.
> [!WARNING]
> **Security Notice:** Basic Authentication stores credentials in environment variables and is less secure than OAuth. Use OAuth for production deployments.
### Configuration
```dotenv
# .env file for BasicAuth mode
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_nextcloud_username
NEXTCLOUD_PASSWORD=your_app_password_or_password
```
### Environment Variables Reference
| Variable | Required | Description |
|----------|----------|-------------|
| `NEXTCLOUD_HOST` | ✅ Yes | Full URL of your Nextcloud instance |
| `NEXTCLOUD_USERNAME` | ✅ Yes | Your Nextcloud username |
| `NEXTCLOUD_PASSWORD` | ✅ Yes | **Recommended:** Use a dedicated [Nextcloud App Password](https://docs.nextcloud.com/server/latest/user_manual/en/session_management.html#managing-devices). Generate one in Nextcloud Security settings. Alternatively, use your login password (less secure). |
---
## Loading Environment Variables
After creating your `.env` file, load the environment variables:
### On Linux/macOS
```bash
# Load all variables from .env
export $(grep -v '^#' .env | xargs)
```
### On Windows (PowerShell)
```powershell
# Load variables from .env
Get-Content .env | ForEach-Object {
if ($_ -match '^\s*([^#][^=]*)\s*=\s*(.*)$') {
[Environment]::SetEnvironmentVariable($matches[1].Trim(), $matches[2].Trim(), "Process")
}
}
```
### Via Docker
```bash
# Docker automatically loads .env when using --env-file
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
```
---
## CLI Configuration
Some configuration options can also be provided via CLI arguments. CLI arguments take precedence over environment variables.
### OAuth-related CLI Options
```bash
uv run nextcloud-mcp-server --help
Options:
--oauth / --no-oauth Force OAuth mode (if enabled) or
BasicAuth mode (if disabled). By default,
auto-detected based on environment
variables.
--oauth-client-id TEXT OAuth client ID (can also use
NEXTCLOUD_OIDC_CLIENT_ID env var)
--oauth-client-secret TEXT OAuth client secret (can also use
NEXTCLOUD_OIDC_CLIENT_SECRET env var)
--oauth-storage-path TEXT Path to store OAuth client credentials
(can also use
NEXTCLOUD_OIDC_CLIENT_STORAGE env var)
[default: .nextcloud_oauth_client.json]
--mcp-server-url TEXT MCP server URL for OAuth callbacks (can
also use NEXTCLOUD_MCP_SERVER_URL env
var) [default: http://localhost:8000]
```
### Server Options
```bash
Options:
-h, --host TEXT Server host [default: 127.0.0.1]
-p, --port INTEGER Server port [default: 8000]
-w, --workers INTEGER Number of worker processes
-r, --reload Enable auto-reload
-l, --log-level [critical|error|warning|info|debug|trace]
Logging level [default: info]
-t, --transport [sse|streamable-http|http]
MCP transport protocol [default: sse]
```
### App Selection
```bash
Options:
-e, --enable-app [notes|tables|webdav|calendar|contacts|deck]
Enable specific Nextcloud app APIs. Can
be specified multiple times. If not
specified, all apps are enabled.
```
### Example CLI Usage
```bash
# OAuth mode with custom client and port
uv run nextcloud-mcp-server --oauth \
--oauth-client-id abc123 \
--oauth-client-secret xyz789 \
--port 8080
# BasicAuth mode with specific apps only
uv run nextcloud-mcp-server --no-oauth \
--enable-app notes \
--enable-app calendar
```
---
## Configuration Best Practices
### For Development
- Use BasicAuth for quick setup and testing
- Or use OAuth with auto-registration (dynamic client registration)
- Store `.env` file in your project directory
- Add `.env` to `.gitignore`
### For Production
- **Always use OAuth2/OIDC** with pre-configured clients
- Store OAuth client credentials securely
- Use environment variables from your deployment platform (Docker secrets, Kubernetes ConfigMaps, etc.)
- Never commit credentials to version control
- Set appropriate file permissions on credential storage:
```bash
chmod 600 .nextcloud_oauth_client.json
```
### For Docker
- Mount OAuth client storage as a volume for persistence:
```bash
docker run -v $(pwd)/.oauth:/app/.oauth --env-file .env \
ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
```
- Use Docker secrets for sensitive values in production
---
## See Also
- [OAuth Setup Guide](oauth-setup.md) - Step-by-step OAuth configuration
- [Authentication](authentication.md) - Authentication modes comparison
- [Running the Server](running.md) - Starting the server with different configurations
- [Troubleshooting](troubleshooting.md) - Common configuration issues
docs/installation.md
+256
View File
@@ -0,0 +1,256 @@
# 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-uv-recommended)
- [Using pip](#using-pip)
- [Using Docker](#using-docker)
- [From Source](#from-source)
---
## Using uv (Recommended)
[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver.
### Install uv
```bash
# 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
```bash
# Install from PyPI
uv pip install nextcloud-mcp-server
# Or install directly using uvx
uvx nextcloud-mcp-server --help
```
### Verify Installation
```bash
uv run nextcloud-mcp-server --help
```
---
## Using pip
Standard installation using pip:
```bash
# 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
```bash
docker pull ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
```
### Run the Container
```bash
# 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`:
```yaml
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:
```bash
docker-compose up -d
```
---
## From Source
Install from the GitHub repository:
### Clone the Repository
```bash
git clone https://github.com/cbcoutinho/nextcloud-mcp-server.git
cd nextcloud-mcp-server
```
### Install Dependencies
#### Using uv (Recommended)
```bash
# Install dependencies
uv sync
# Install development dependencies (optional)
uv sync --group dev
```
#### Using pip
```bash
# 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
```bash
# 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](configuration.md)
2. **Set up authentication** - See [OAuth Setup Guide](oauth-setup.md) or [Authentication](authentication.md)
3. **Run the server** - See [Running the Server](running.md)
## Updating
### Update with uv
```bash
uv pip install --upgrade nextcloud-mcp-server
```
### Update with pip
```bash
pip install --upgrade nextcloud-mcp-server
```
### Update Docker Image
```bash
docker pull ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
docker-compose up -d # Restart with new image
```
### Update from Source
```bash
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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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](configuration.md) - Environment variables and settings
- [OAuth Setup Guide](oauth-setup.md) - OAuth authentication setup
- [Running the Server](running.md) - Starting and managing the server
docs/oauth-setup.md
+225
View File
@@ -0,0 +1,225 @@
# OAuth Setup Guide
This guide walks you through setting up OAuth2/OIDC authentication for the Nextcloud MCP server.
## Prerequisites
- Nextcloud instance with administrator access
- Python 3.11+ installed
- Nextcloud MCP server installed (see [Installation Guide](installation.md))
## Step 1: Install Nextcloud OIDC App
1. Open your Nextcloud instance as an administrator
2. Navigate to **Apps** → **Security**
3. Find and install the **OpenID Connect user backend** app
4. Enable the app
## Step 2: Enable Dynamic Client Registration
1. Navigate to **Settings** → **OIDC** (in Administration settings)
2. Find the **Dynamic Client Registration** section
3. Enable **"Allow dynamic client registration"**
4. (Optional) Configure client expiration time:
```bash
# Via Nextcloud CLI (occ) - optional, default is 3600 seconds (1 hour)
php occ config:app:set oidc expire_time --value "86400" # 24 hours
```
## Step 3: Choose Your Setup Approach
You have two options for configuring OAuth clients:
### Approach A: Automatic Registration (Zero-config)
**Best for:** Development, testing, short-lived deployments
**How it works:** The MCP server automatically registers a new OAuth client with Nextcloud at startup using dynamic client registration.
**Pros:**
- Zero configuration required
- Quick to set up
- No manual client management
**Cons:**
- Clients expire (default: 1 hour)
- Server must re-register on restart if expired
- Not recommended for long-running production deployments
[Jump to Approach A setup →](#approach-a-automatic-registration)
### Approach B: Pre-configured Client (Production)
**Best for:** Production, long-running deployments
**How it works:** You manually create an OAuth client via Nextcloud CLI and provide credentials to the MCP server.
**Pros:**
- Credentials don't expire
- Stable for production use
- More control over client configuration
**Cons:**
- Requires manual setup
- Needs access to Nextcloud server CLI
[Jump to Approach B setup →](#approach-b-pre-configured-client)
---
## Approach A: Automatic Registration
### 1. Configure Environment
Create your `.env` file with only the Nextcloud host:
```dotenv
# .env file
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
# Leave these EMPTY for OAuth mode
NEXTCLOUD_USERNAME=
NEXTCLOUD_PASSWORD=
```
### 2. Start the MCP Server
```bash
# Load environment variables
export $(grep -v '^#' .env | xargs)
# Start server with OAuth enabled
uv run nextcloud-mcp-server --oauth
```
### 3. Verify Registration
The server will automatically register a new OAuth client. Look for these log messages:
```
INFO OAuth mode detected (NEXTCLOUD_USERNAME/PASSWORD not set)
INFO Configuring MCP server for OAuth mode
INFO Performing OIDC discovery: https://your.nextcloud.instance.com/.well-known/openid-configuration
INFO OIDC discovery successful
INFO Attempting dynamic client registration...
INFO Dynamic client registration successful
INFO OAuth client ready: <client-id>...
INFO Saved OAuth client credentials to .nextcloud_oauth_client.json
INFO OAuth initialization complete
```
### 4. Client Credential Storage
Registered client credentials are saved to `.nextcloud_oauth_client.json` by default. The server will:
- Load existing credentials on startup
- Check if they've expired
- Re-register automatically if expired or missing
**Note:** Since dynamically registered clients expire (default: 1 hour), the server checks credentials at startup. For long-running deployments, consider using Approach B (pre-configured clients) instead.
---
## Approach B: Pre-configured Client
### 1. Register Client via Nextcloud CLI
SSH into your Nextcloud server and run:
```bash
# Create OAuth client
php occ oidc:create \
--name="Nextcloud MCP Server" \
--type=confidential \
--redirect-uri="http://localhost:8000/oauth/callback"
# Example output:
# Client ID: abc123xyz
# Client Secret: secret456def
```
**Note:** Adjust the `--redirect-uri` to match your MCP server URL if different from `http://localhost:8000`.
### 2. Configure Environment
Add the client credentials to your `.env` file:
```dotenv
# .env file
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
# OAuth Client Credentials
NEXTCLOUD_OIDC_CLIENT_ID=abc123xyz
NEXTCLOUD_OIDC_CLIENT_SECRET=secret456def
# Optional: Custom OAuth configuration
NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
NEXTCLOUD_OIDC_CLIENT_STORAGE=.nextcloud_oauth_client.json
# Leave these EMPTY for OAuth mode
NEXTCLOUD_USERNAME=
NEXTCLOUD_PASSWORD=
```
See [Configuration Guide](configuration.md#oauth2oidc-configuration) for all available options.
### 3. Start the MCP Server
```bash
# Load environment variables
export $(grep -v '^#' .env | xargs)
# Start server - it will use pre-configured credentials
uv run nextcloud-mcp-server --oauth
```
### 4. Verify Configuration
Look for these log messages:
```
INFO OAuth mode detected (NEXTCLOUD_USERNAME/PASSWORD not set)
INFO Configuring MCP server for OAuth mode
INFO Performing OIDC discovery: https://your.nextcloud.instance.com/.well-known/openid-configuration
INFO OIDC discovery successful
INFO Using pre-configured OAuth client: abc123xyz
INFO OAuth initialization complete
```
**Benefits:** Pre-configured clients don't expire automatically and are more stable for production use.
---
## Step 4: Test Authentication
The MCP server is now configured for OAuth. When clients connect:
1. Client connects to MCP server
2. Server provides OAuth authorization URL
3. User opens URL in browser and authenticates to Nextcloud
4. Nextcloud redirects back with authorization code
5. Client exchanges code for access token
6. Client uses Bearer token to access MCP server
7. All Nextcloud API requests use the user's OAuth token
### Test with MCP Inspector
```bash
# Start MCP Inspector
uv run mcp dev
# In the browser UI:
# 1. Enter your MCP server URL (e.g., http://localhost:8000)
# 2. Complete OAuth flow in browser
# 3. Test tools and resources
```
## Next Steps
- [Running the Server](running.md) - Additional server options
- [Configuration](configuration.md) - All environment variables
- [Troubleshooting](troubleshooting.md) - Common OAuth issues
## See Also
- [Authentication Overview](authentication.md) - OAuth vs BasicAuth comparison
- [OAuth Bearer Token Issue](oauth2-bearer-token-session-issue.md) - Required patch for non-OCS endpoints