nextcloud-mcp-server/docs/configuration.md

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:

cp env.sample .env
# Edit .env with your Nextcloud details

Then choose your authentication mode:

• OAuth2/OIDC Configuration (Recommended)
• Basic Authentication Configuration

---

OAuth2/OIDC Configuration

OAuth2/OIDC is the recommended authentication mode for production deployments.

Minimal Configuration (Auto-registration)

# .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)

# .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 Callback Settings (optional)
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_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 required Nextcloud apps (both are required):

   • oidc - OIDC Identity Provider (Apps → Security)
   • user_oidc - OpenID Connect user backend (Apps → Security)

2. Configure the apps:

   • Enable dynamic client registration (if using auto-registration) - Settings → OIDC
   • Enable Bearer token validation: php occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean

3. Apply Bearer token patch - The user_oidc app requires a patch for non-OCS endpoints - See Upstream Status for details

See the OAuth Setup Guide for detailed step-by-step instructions, or OAuth Quick Start for a 5-minute setup.

---

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

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

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

On Windows (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

# 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

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)
  --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

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

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

# 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
• SQLite database permissions are handled automatically by the server

For Docker

• Mount OAuth client storage as a volume for persistence:

  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 Quick Start - 5-minute OAuth setup for development
• OAuth Setup Guide - Detailed OAuth configuration for production
• OAuth Architecture - How OAuth works in the MCP server
• Upstream Status - Required patches and upstream PRs
• Authentication - Authentication modes comparison
• Running the Server - Starting the server with different configurations
• Troubleshooting - Common configuration issues
• OAuth Troubleshooting - OAuth-specific troubleshooting