brandon/nextcloud-mcp-server

Fork 0

Files

T

Chris Coutinho 2489a714b8 docs: Update README and docs

2025-10-14 01:23:37 +02:00

6.3 KiB

Raw Blame History

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)

Step 1: Install Nextcloud OIDC App

Open your Nextcloud instance as an administrator
Navigate to Apps → Security
Find and install the OpenID Connect user backend app
Enable the app

Step 2: Enable Dynamic Client Registration

Navigate to Settings → OIDC (in Administration settings)
Find the Dynamic Client Registration section
Enable "Allow dynamic client registration"

(Optional) Configure client expiration time:

# 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 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 A: Automatic Registration

1. Configure Environment

Create your .env file with only the Nextcloud host:

# .env file
NEXTCLOUD_HOST=https://your.nextcloud.instance.com

# Leave these EMPTY for OAuth mode
NEXTCLOUD_USERNAME=
NEXTCLOUD_PASSWORD=

2. Start the MCP Server

# 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:

# 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:

# .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 for all available options.

3. Start the MCP Server

# 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:

Client connects to MCP server
Server provides OAuth authorization URL
User opens URL in browser and authenticates to Nextcloud
Nextcloud redirects back with authorization code
Client exchanges code for access token
Client uses Bearer token to access MCP server
All Nextcloud API requests use the user's OAuth token

Test with MCP Inspector

# 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 - Additional server options
Configuration - All environment variables
Troubleshooting - Common OAuth issues

6.3 KiB Raw Blame History