Nextcloud MCP Server

# Keycloak OAuth Configuration for Nextcloud MCP Server # # This configuration uses Keycloak as the OAuth/OIDC identity provider # while still accessing Nextcloud APIs. Nextcloud's user_oidc app validates # Keycloak bearer tokens and provisions users automatically. # # Architecture: Client → Keycloak (OAuth) → MCP Server → Nextcloud (user_oidc validates) → APIs # # This enables ADR-002 authentication patterns without admin credentials! # ============================================================================== # OAUTH PROVIDER SELECTION # ============================================================================== # OAuth provider: "keycloak" or "nextcloud" (default) OAUTH_PROVIDER=keycloak # ============================================================================== # KEYCLOAK CONFIGURATION # ============================================================================== # Keycloak base URL (accessible from MCP server container) KEYCLOAK_URL=http://keycloak:8080 # Keycloak realm name KEYCLOAK_REALM=nextcloud-mcp # OAuth client credentials (from Keycloak realm export or manual configuration) KEYCLOAK_CLIENT_ID=nextcloud-mcp-server KEYCLOAK_CLIENT_SECRET=mcp-secret-change-in-production # OIDC discovery URL (auto-constructed from URL + realm, or specify explicitly) KEYCLOAK_DISCOVERY_URL=http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration # ============================================================================== # NEXTCLOUD CONFIGURATION # ============================================================================== # Nextcloud URL (accessible from MCP server container) # Used for API access - Keycloak tokens are validated by user_oidc app NEXTCLOUD_HOST=http://app:80 # MCP server URL (for OAuth redirect URIs) # This is the publicly accessible URL that OAuth clients connect to NEXTCLOUD_MCP_SERVER_URL=http://localhost:8002 # Public Keycloak issuer URL (accessible from OAuth clients) # If clients access Keycloak via a different URL than the internal one, # set this to the public URL for OAuth flows NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8888 # ============================================================================== # REFRESH TOKEN STORAGE (ADR-002 Tier 1: Offline Access) # ============================================================================== # Enable offline_access scope to get refresh tokens ENABLE_OFFLINE_ACCESS=true # Encryption key for storing refresh tokens (generate with instructions below) # IMPORTANT: Keep this secret! Tokens are encrypted at rest using this key. # # Generate a key: # python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" # # Example (DO NOT use this in production!): # TOKEN_ENCRYPTION_KEY=your-base64-encoded-fernet-key-here # Path to SQLite database for token storage TOKEN_STORAGE_DB=/app/data/tokens.db # ============================================================================== # DOCKER COMPOSE NOTES # ============================================================================== # When running via docker-compose, the mcp-keycloak service is pre-configured # with these environment variables. See docker-compose.yml for the full config. # # Start services: # docker-compose up -d keycloak app mcp-keycloak # # View logs: # docker-compose logs -f mcp-keycloak # # Check Keycloak realm: # curl http://localhost:8888/realms/nextcloud-mcp/.well-known/openid-configuration # # Check user_oidc provider: # docker compose exec app php occ user_oidc:provider keycloak # ============================================================================== # KEYCLOAK SETUP VERIFICATION # ============================================================================== # 1. Verify Keycloak is running and realm is imported: # curl http://localhost:8888/realms/nextcloud-mcp/.well-known/openid-configuration # # 2. Verify Nextcloud user_oidc provider is configured: # docker compose exec app php occ user_oidc:provider keycloak # # 3. Test OAuth flow manually: # - Get token from Keycloak: # curl -X POST "http://localhost:8888/realms/nextcloud-mcp/protocol/openid-connect/token" \ # -d "grant_type=password" \ # -d "client_id=nextcloud-mcp-server" \ # -d "client_secret=mcp-secret-change-in-production" \ # -d "username=admin" \ # -d "password=admin" \ # -d "scope=openid profile email offline_access" # # - Use token with Nextcloud API: # curl -H "Authorization: Bearer <access_token>" \ # http://localhost:8080/ocs/v2.php/cloud/capabilities # # 4. Connect MCP client to server: # - Point your MCP client to http://localhost:8002 # - Complete OAuth flow via Keycloak (credentials: admin/admin) # - Client should receive access token and be able to call MCP tools # ============================================================================== # TROUBLESHOOTING # ============================================================================== # If OAuth flow fails: # - Check that Keycloak is accessible: curl http://localhost:8888 # - Check that user_oidc provider is configured: docker compose exec app php occ user_oidc:provider keycloak # - Check MCP server logs: docker-compose logs mcp-keycloak # - Verify redirect URIs match in Keycloak client configuration # # If token validation fails: # - Verify user_oidc has bearer validation enabled (--check-bearer=1) # - Check Nextcloud logs: docker compose exec app tail -f /var/www/html/data/nextcloud.log # - Verify Keycloak discovery URL is accessible from Nextcloud container: # docker compose exec app curl http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration # # If offline_access/refresh tokens not working: # - Verify TOKEN_ENCRYPTION_KEY is set and valid # - Check token storage database: ls -lah /app/data/tokens.db (inside container) # - Check that offline_access scope is requested in realm configuration