docs: Update README and docs
This commit is contained in:
Chris Coutinho
@@ -8,6 +8,39 @@ The Nextcloud MCP (Model Context Protocol) server allows Large Language Models (
|
||||
|
||||
The server provides integration with multiple Nextcloud apps, enabling LLMs to interact with your Nextcloud data through a rich set of tools and resources.
|
||||
|
||||
## Authentication Modes
|
||||
|
||||
The Nextcloud MCP server supports two authentication modes:
|
||||
|
||||
| Mode | Status | Security | Use Case |
|
||||
|------|--------|----------|----------|
|
||||
| **OAuth2/OIDC** | ✅ Recommended | 🔒 High | Production deployments, multi-user scenarios |
|
||||
| **Basic Auth** | ⚠️ Legacy | ⚠️ Lower | Development, backward compatibility |
|
||||
|
||||
### OAuth2/OIDC (Recommended)
|
||||
- **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
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Current Implementation Limitations:**
|
||||
> - 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 [docs/oauth2-bearer-token-session-issue.md](docs/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
|
||||
|
||||
### Basic Authentication (Legacy)
|
||||
- **Simple setup** with username/password
|
||||
- **Single-user** server instances
|
||||
- **Credentials in environment** (less secure)
|
||||
- **Maintained for compatibility** - will be deprecated in future versions
|
||||
|
||||
**How it works:** 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
|
||||
|
||||
## Supported Nextcloud Apps
|
||||
|
||||
| App | Support Status | Description |
|
||||
@@ -126,18 +159,156 @@ A pre-built Docker image is available: `ghcr.io/cbcoutinho/nextcloud-mcp-server`
|
||||
|
||||
## Configuration
|
||||
|
||||
The server requires credentials to connect to your Nextcloud instance. Create a file named `.env` (or any name you prefer) in the directory where you'll run the server, based on the `env.sample` file:
|
||||
The server requires configuration to connect to your Nextcloud instance. Create a file named `.env` (or any name you prefer) in the directory where you'll run the server, based on the `env.sample` file.
|
||||
|
||||
### Option 1: OAuth2/OIDC Configuration (Recommended)
|
||||
|
||||
```dotenv
|
||||
# .env
|
||||
# .env file for OAuth mode
|
||||
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
|
||||
|
||||
# OAuth Configuration (Optional - auto-registers if not provided)
|
||||
NEXTCLOUD_OIDC_CLIENT_ID=
|
||||
NEXTCLOUD_OIDC_CLIENT_SECRET=
|
||||
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:**
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
|----------|----------|---------|-------------|
|
||||
| `NEXTCLOUD_HOST` | ✅ Yes | - | Full URL of your Nextcloud instance |
|
||||
| `NEXTCLOUD_OIDC_CLIENT_ID` | ⚠️ Optional | - | Pre-configured OAuth client ID (auto-registers if empty) |
|
||||
| `NEXTCLOUD_OIDC_CLIENT_SECRET` | ⚠️ Optional | - | Pre-configured OAuth client secret |
|
||||
| `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 |
|
||||
|
||||
**Prerequisites:**
|
||||
- Nextcloud OIDC app installed and enabled
|
||||
- Dynamic Client Registration enabled (for auto-registration)
|
||||
- See [OAuth Setup Guide](#oauth-setup-guide) below for detailed instructions
|
||||
|
||||
### Option 2: Basic Authentication (Legacy)
|
||||
|
||||
> [!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.
|
||||
|
||||
```dotenv
|
||||
# .env file for BasicAuth mode
|
||||
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
|
||||
NEXTCLOUD_USERNAME=your_nextcloud_username
|
||||
NEXTCLOUD_PASSWORD=your_nextcloud_app_password_or_login_password
|
||||
NEXTCLOUD_PASSWORD=your_app_password_or_password
|
||||
```
|
||||
|
||||
**Environment Variables:**
|
||||
|
||||
* `NEXTCLOUD_HOST`: The full URL of your Nextcloud instance.
|
||||
* `NEXTCLOUD_USERNAME`: Your Nextcloud username.
|
||||
* `NEXTCLOUD_PASSWORD`: **Important:** It is highly recommended to use a dedicated Nextcloud App Password for security. You can generate one in your Nextcloud Security settings. Alternatively, you can use your regular login password, but this is less secure.
|
||||
* `NEXTCLOUD_PASSWORD`: **Important:** Use a dedicated Nextcloud App Password for security. Generate one in your Nextcloud Security settings. Alternatively, use your login password (less secure).
|
||||
|
||||
## OAuth Setup Guide
|
||||
|
||||
This guide walks you through setting up OAuth2/OIDC authentication for the Nextcloud MCP server.
|
||||
|
||||
### 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: Configure MCP Server
|
||||
|
||||
Choose one of two approaches:
|
||||
|
||||
#### Approach A: Automatic Registration (Zero-config)
|
||||
|
||||
**Best for:** Development, testing, short-lived deployments
|
||||
|
||||
1. Create your `.env` file with only the host:
|
||||
```dotenv
|
||||
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
|
||||
```
|
||||
|
||||
2. Start the MCP server:
|
||||
```bash
|
||||
export $(grep -v '^#' .env | xargs)
|
||||
uv run nextcloud-mcp-server --oauth
|
||||
```
|
||||
|
||||
3. The server will automatically:
|
||||
- Register a new OAuth client with Nextcloud
|
||||
- Save credentials to `.nextcloud_oauth_client.json`
|
||||
- Display registration confirmation in logs
|
||||
|
||||
**Note:** Dynamically registered clients expire after 1 hour by default. The server checks credentials at startup and re-registers if expired. For long-running deployments, consider Approach B.
|
||||
|
||||
#### Approach B: Pre-configured Client (Production)
|
||||
|
||||
**Best for:** Production, long-running deployments
|
||||
|
||||
1. Register a client via Nextcloud CLI:
|
||||
```bash
|
||||
# SSH into your Nextcloud server
|
||||
php occ oidc:create \
|
||||
--name="Nextcloud MCP Server" \
|
||||
--type=confidential \
|
||||
--redirect-uri="http://localhost:8000/oauth/callback"
|
||||
|
||||
# Note the client_id and client_secret from output
|
||||
```
|
||||
|
||||
2. Add credentials to your `.env` file:
|
||||
```dotenv
|
||||
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
|
||||
NEXTCLOUD_OIDC_CLIENT_ID=your-client-id-here
|
||||
NEXTCLOUD_OIDC_CLIENT_SECRET=your-client-secret-here
|
||||
```
|
||||
|
||||
3. Start the server - it will use the pre-configured credentials
|
||||
|
||||
**Benefits:** Pre-configured clients don't expire automatically and are more stable for production use.
|
||||
|
||||
### Step 4: Verify OAuth Configuration
|
||||
|
||||
Start the server and 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 OAuth client ready: <client-id>...
|
||||
INFO OAuth initialization complete
|
||||
```
|
||||
|
||||
### Step 5: Test Authentication
|
||||
|
||||
The MCP server is now configured for OAuth. When clients connect:
|
||||
|
||||
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.
|
||||
|
||||
## Transport Types
|
||||
|
||||
@@ -179,19 +350,45 @@ docker run -p 127.0.0.1:8000:8000 --env-file .env --rm ghcr.io/cbcoutinho/nextcl
|
||||
|
||||
Ensure your environment variables are loaded, then run the server. You have several options:
|
||||
|
||||
#### Option 1: Using `nextcloud_mcp_server` cli (recommended)
|
||||
#### Option 1: Using `nextcloud-mcp-server` CLI (recommended)
|
||||
|
||||
**OAuth Mode (Recommended):**
|
||||
```bash
|
||||
# Load environment variables from your .env file
|
||||
export $(grep -v '^#' .env | xargs)
|
||||
|
||||
# Run the app module directly with custom options
|
||||
uv run python -m nextcloud_mcp_server.app --host 0.0.0.0 --port 8080 --log-level info
|
||||
# Start with OAuth (auto-detected when USERNAME/PASSWORD not set)
|
||||
uv run nextcloud-mcp-server --host 0.0.0.0 --port 8000
|
||||
|
||||
# Explicitly force OAuth mode
|
||||
uv run nextcloud-mcp-server --oauth
|
||||
|
||||
# OAuth with custom configuration
|
||||
uv run nextcloud-mcp-server --oauth \
|
||||
--oauth-client-id=your-client-id \
|
||||
--oauth-client-secret=your-client-secret
|
||||
|
||||
# OAuth with specific apps enabled
|
||||
uv run nextcloud-mcp-server --oauth \
|
||||
--enable-app notes --enable-app calendar
|
||||
```
|
||||
|
||||
**BasicAuth Mode (Legacy):**
|
||||
```bash
|
||||
# Load environment variables from your .env file (with USERNAME/PASSWORD set)
|
||||
export $(grep -v '^#' .env | xargs)
|
||||
|
||||
# Start with BasicAuth (auto-detected when USERNAME/PASSWORD are set)
|
||||
uv run nextcloud-mcp-server --host 0.0.0.0 --port 8000
|
||||
|
||||
# Explicitly force BasicAuth mode
|
||||
uv run nextcloud-mcp-server --no-oauth
|
||||
|
||||
# Enable only specific Nextcloud app APIs
|
||||
uv run python -m nextcloud_mcp_server.app --enable-app notes --enable-app calendar
|
||||
uv run nextcloud-mcp-server --enable-app notes --enable-app calendar
|
||||
|
||||
# Enable only WebDAV for file operations
|
||||
uv run python -m nextcloud_mcp_server.app --enable-app webdav
|
||||
uv run nextcloud-mcp-server --enable-app webdav
|
||||
```
|
||||
|
||||
#### Option 2: Using `uvicorn`
|
||||
@@ -245,21 +442,44 @@ This can be useful for:
|
||||
|
||||
Mount your environment file when running the container:
|
||||
|
||||
**OAuth Mode:**
|
||||
```bash
|
||||
# Run with all apps enabled (default)
|
||||
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
|
||||
# Run with OAuth (auto-detected when USERNAME/PASSWORD not in .env)
|
||||
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
|
||||
ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
|
||||
|
||||
# OAuth with persistent client 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
|
||||
|
||||
# OAuth with specific apps enabled
|
||||
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
|
||||
ghcr.io/cbcoutinho/nextcloud-mcp-server:latest \
|
||||
--oauth --enable-app notes --enable-app calendar
|
||||
```
|
||||
|
||||
**BasicAuth Mode (Legacy):**
|
||||
```bash
|
||||
# Run with BasicAuth (auto-detected when USERNAME/PASSWORD in .env)
|
||||
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
|
||||
ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
|
||||
|
||||
# Run with only specific apps enabled
|
||||
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm ghcr.io/cbcoutinho/nextcloud-mcp-server:latest \
|
||||
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
|
||||
ghcr.io/cbcoutinho/nextcloud-mcp-server:latest \
|
||||
--enable-app notes --enable-app calendar
|
||||
|
||||
# Run with only WebDAV
|
||||
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm ghcr.io/cbcoutinho/nextcloud-mcp-server:latest \
|
||||
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
|
||||
ghcr.io/cbcoutinho/nextcloud-mcp-server:latest \
|
||||
--enable-app webdav
|
||||
```
|
||||
|
||||
This will start the server and expose it on port 8000 of your local machine.
|
||||
|
||||
**Note for OAuth:** When using OAuth with Docker, ensure the `NEXTCLOUD_MCP_SERVER_URL` in your `.env` file matches the accessible URL of the container (e.g., `http://localhost:8000` for local development).
|
||||
|
||||
## Usage
|
||||
|
||||
Once the server is running, you can connect to it using an MCP client like `MCP Inspector`. Once your MCP server is running, launch MCP Inspector as follows:
|
||||
@@ -270,6 +490,144 @@ uv run mcp dev
|
||||
|
||||
You can then connect to and interact with the server's tools and resources through your browser.
|
||||
|
||||
## Troubleshooting OAuth
|
||||
|
||||
### Issue: "OAuth mode requires NEXTCLOUD_HOST environment variable"
|
||||
|
||||
**Cause:** The `NEXTCLOUD_HOST` environment variable is not set or empty.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Ensure NEXTCLOUD_HOST is set in your .env file
|
||||
echo "NEXTCLOUD_HOST=https://your.nextcloud.instance.com" >> .env
|
||||
|
||||
# Load environment variables
|
||||
export $(grep -v '^#' .env | xargs)
|
||||
```
|
||||
|
||||
### Issue: "OAuth mode requires either client credentials OR dynamic client registration"
|
||||
|
||||
**Cause:** The Nextcloud OIDC app either:
|
||||
1. Is not installed
|
||||
2. Doesn't have dynamic client registration enabled
|
||||
3. Isn't providing a registration endpoint
|
||||
|
||||
**Solution:**
|
||||
1. Verify OIDC app is installed: Navigate to Nextcloud **Apps** → **Security**
|
||||
2. Enable dynamic client registration:
|
||||
- Go to **Settings** → **OIDC** (Administration)
|
||||
- Enable "Allow dynamic client registration"
|
||||
3. Or provide pre-configured credentials:
|
||||
```dotenv
|
||||
NEXTCLOUD_OIDC_CLIENT_ID=your-client-id
|
||||
NEXTCLOUD_OIDC_CLIENT_SECRET=your-client-secret
|
||||
```
|
||||
|
||||
### Issue: "Stored client has expired"
|
||||
|
||||
**Cause:** Dynamically registered OAuth clients expire (default: 1 hour).
|
||||
|
||||
**Solution:**
|
||||
|
||||
**Option 1:** Restart the server - it will automatically re-register
|
||||
```bash
|
||||
# Server checks credentials at startup and re-registers if expired
|
||||
uv run nextcloud-mcp-server --oauth
|
||||
```
|
||||
|
||||
**Option 2:** Use pre-configured credentials (recommended for production)
|
||||
```bash
|
||||
# Register permanent client via Nextcloud CLI
|
||||
php occ oidc:create \
|
||||
--name="Nextcloud MCP Server" \
|
||||
--type=confidential \
|
||||
--redirect-uri="http://localhost:8000/oauth/callback"
|
||||
|
||||
# Add to .env
|
||||
NEXTCLOUD_OIDC_CLIENT_ID=<from-output>
|
||||
NEXTCLOUD_OIDC_CLIENT_SECRET=<from-output>
|
||||
```
|
||||
|
||||
**Option 3:** Increase expiration time
|
||||
```bash
|
||||
# Via Nextcloud occ command
|
||||
php occ config:app:set oidc expire_time --value "86400" # 24 hours
|
||||
```
|
||||
|
||||
### Issue: "HTTP 401 Unauthorized" when calling Nextcloud APIs
|
||||
|
||||
**Cause:** OAuth tokens may not work with certain Nextcloud endpoints due to CORS middleware session handling.
|
||||
|
||||
**Solution:** This is a known issue with the Nextcloud OIDC app. See [docs/oauth2-bearer-token-session-issue.md](docs/oauth2-bearer-token-session-issue.md) for details and workarounds.
|
||||
|
||||
The issue affects app-specific APIs (like Notes) but not OCS APIs. A patch for the `user_oidc` app is available in the documentation.
|
||||
|
||||
### Issue: "Permission denied" when reading/writing client credentials file
|
||||
|
||||
**Cause:** The server cannot access the OAuth client storage file.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Check file permissions
|
||||
ls -la .nextcloud_oauth_client.json
|
||||
|
||||
# Fix permissions (should be 0600)
|
||||
chmod 600 .nextcloud_oauth_client.json
|
||||
|
||||
# Ensure the directory is writable
|
||||
chmod 755 $(dirname .nextcloud_oauth_client.json)
|
||||
```
|
||||
|
||||
### Issue: Switching Between OAuth and BasicAuth
|
||||
|
||||
**To switch from BasicAuth to OAuth:**
|
||||
```bash
|
||||
# Remove or comment out USERNAME/PASSWORD in .env
|
||||
# Keep only NEXTCLOUD_HOST
|
||||
sed -i 's/^NEXTCLOUD_USERNAME/#NEXTCLOUD_USERNAME/' .env
|
||||
sed -i 's/^NEXTCLOUD_PASSWORD/#NEXTCLOUD_PASSWORD/' .env
|
||||
|
||||
# Restart server with --oauth flag
|
||||
uv run nextcloud-mcp-server --oauth
|
||||
```
|
||||
|
||||
**To switch from OAuth to BasicAuth:**
|
||||
```bash
|
||||
# Add USERNAME/PASSWORD to .env
|
||||
echo "NEXTCLOUD_USERNAME=your-username" >> .env
|
||||
echo "NEXTCLOUD_PASSWORD=your-password" >> .env
|
||||
|
||||
# Restart server with --no-oauth flag (or let auto-detection work)
|
||||
uv run nextcloud-mcp-server --no-oauth
|
||||
```
|
||||
|
||||
### Getting Help
|
||||
|
||||
If you continue to experience issues:
|
||||
|
||||
1. **Check logs:** Run with `--log-level debug` for detailed output
|
||||
```bash
|
||||
uv run nextcloud-mcp-server --oauth --log-level debug
|
||||
```
|
||||
|
||||
2. **Verify OIDC discovery:** Check if the discovery endpoint is accessible
|
||||
```bash
|
||||
curl https://your.nextcloud.instance.com/.well-known/openid-configuration
|
||||
```
|
||||
|
||||
3. **Check dynamic registration:** Verify the endpoint exists in the discovery response
|
||||
```json
|
||||
{
|
||||
"registration_endpoint": "https://your.nextcloud.instance.com/apps/oidc/register"
|
||||
}
|
||||
```
|
||||
|
||||
4. **Open an issue:** If problems persist, open an issue on the [GitHub repository](https://github.com/cbcoutinho/nextcloud-mcp-server/issues) with:
|
||||
- Server logs (with `--log-level debug`)
|
||||
- Nextcloud version
|
||||
- OIDC app version
|
||||
- Error messages
|
||||
|
||||
## References:
|
||||
|
||||
- https://github.com/modelcontextprotocol/python-sdk
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user