mcp-nextcloud/docs/running.md

# Running the Server

This guide covers different ways to start and run the Nextcloud MCP server.

## Prerequisites

Before running the server:

1. **Install the server** - See [Installation Guide](installation.md)
2. **Configure environment** - See [Configuration Guide](configuration.md)
3. **Set up authentication** - See [OAuth Setup](oauth-setup.md) or [Authentication](authentication.md)

---

## Quick Start

Start the server using Docker:

```bash
# OAuth mode (recommended)
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth

# BasicAuth mode
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
```

The server will start on `http://127.0.0.1:8000` by default.

---

## Running with Docker

### Basic Docker Run

#### OAuth Mode (Recommended)

```bash
# OAuth with auto-registration
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth

# OAuth with custom port
docker run -p 127.0.0.1:8080:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth

# OAuth with pre-configured client
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  -e NEXTCLOUD_OIDC_CLIENT_ID=abc123 \
  -e NEXTCLOUD_OIDC_CLIENT_SECRET=xyz789 \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth

# OAuth with specific apps only
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
# BasicAuth (requires NEXTCLOUD_USERNAME/PASSWORD in .env)
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest

# BasicAuth with specific apps
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 webdav
```

### Docker with Persistent Token Storage

```bash
# Mount volume for persistent OAuth token storage
docker run -p 127.0.0.1:8000:8000 --env-file .env \
  -v $(pwd)/data:/app/data \
  --rm ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
```

### Docker Compose

Create `docker-compose.yml`:

```yaml
version: '3.8'

services:
  mcp:
    image: ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
    command: --oauth --enable-app notes --enable-app calendar
    ports:
      - "127.0.0.1:8000:8000"
    env_file:
      - .env
    volumes:
      - ./data:/app/data  # Persistent token storage
    restart: unless-stopped
```

Start the service:

```bash
# Start in foreground
docker-compose up

# Start in background
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down
```

---

## Server Options

### Host and Port

```bash
# Bind to all interfaces (accessible from network)
docker run -p 0.0.0.0:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth

# Bind to localhost only (default, more secure)
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth

# Use a different port (map host port 8080 to container port 8000)
docker run -p 127.0.0.1:8080:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
```

**Security Note:** Binding to `0.0.0.0` exposes the server to your network. Only use this if you understand the security implications.

### Transport Protocols

The server supports multiple MCP transport protocols:

```bash
# Streamable HTTP (default, recommended)
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
  --transport streamable-http

# SSE - Server-Sent Events (deprecated)
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
  --transport sse

# HTTP
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
  --transport http
```

> [!WARNING]
> SSE transport is deprecated and will be removed in a future version of the MCP spec. Please migrate to `streamable-http`.

### Logging

```bash
# Set log level (critical, error, warning, info, debug, trace)
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
  --log-level debug

# Production: use warning or error
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
  --log-level warning
```

### Selective App Enablement

By default, all supported Nextcloud apps are enabled. You can enable specific apps only:

```bash
# Available apps: notes, tables, webdav, calendar, contacts, cookbook, deck

# Enable all apps (default)
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth

# Enable only Notes
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 multiple apps
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 --enable-app contacts

# Enable only WebDAV for file operations
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
  --enable-app webdav
```

**Use cases:**
- Reduce memory usage and startup time
- Limit functionality for security/organizational reasons
- Test specific app integrations
- Run lightweight instances with only needed features

---

## Development Mode

### Running for Development

For active development with auto-reload, mount your source code as a volume:

```bash
# Development mode with source code mounted
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  -v $(pwd):/app \
  -v $(pwd)/data:/app/data \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
  --log-level debug
```

For local development without Docker:

```bash
# Load environment variables
export $(grep -v '^#' .env | xargs)

# Run the server with auto-reload
uv run nextcloud-mcp-server run --oauth --log-level debug
```

### CLI Subcommands

The `nextcloud-mcp-server` CLI has two main subcommands:

1. **`run`** - Start the MCP server (default command in Docker)
   ```bash
   uv run nextcloud-mcp-server run --oauth --host 0.0.0.0 --port 8000
   ```

2. **`db`** - Database migration management (Alembic)
   ```bash
   # Show current migration revision
   uv run nextcloud-mcp-server db current

   # Upgrade to latest migration
   uv run nextcloud-mcp-server db upgrade

   # Show migration history
   uv run nextcloud-mcp-server db history

   # Create new migration (developers only)
   uv run nextcloud-mcp-server db migrate "description of changes"
   ```

### Database Migrations

Token storage uses **Alembic** for schema management:

- **Automatic migrations**: Database is upgraded automatically on server startup
- **Backward compatibility**: Pre-Alembic databases are automatically stamped with the initial revision
- **Migration files**: Located in `alembic/versions/`
- **For developers**: When changing the schema:
  1. Create a migration: `uv run nextcloud-mcp-server db migrate "add new column"`
  2. Edit the generated file in `alembic/versions/` to add SQL statements
  3. Test upgrade: `uv run nextcloud-mcp-server db upgrade`
  4. Test downgrade: `uv run nextcloud-mcp-server db downgrade`

See [Database Migrations Guide](database-migrations.md) for detailed information.

---

## Connecting to the Server

### Using MCP Inspector

MCP Inspector is a browser-based tool for testing MCP servers:

1. Start your MCP server using Docker (see above)
2. Start MCP Inspector:
   ```bash
   npx @modelcontextprotocol/inspector
   ```
3. In the browser:
   - Enter server URL: `http://localhost:8000`
   - Complete OAuth flow (if using OAuth)
   - Explore tools and resources

### Using MCP Clients

MCP clients (like Claude Desktop, LLM IDEs) can connect to your server:

1. Configure the client with your server URL
2. Complete OAuth authentication (if enabled)
3. Start interacting with Nextcloud through the LLM

---

## Verifying Server Status

### Check Server Health

```bash
# Test if server is responding
curl http://localhost:8000/health

# Expected response: HTTP 200 OK
```

### Check OAuth Configuration

Look for these log messages on startup:

**OAuth mode:**
```
INFO     OAuth mode detected (NEXTCLOUD_USERNAME/PASSWORD not set)
INFO     Configuring MCP server for OAuth mode
INFO     OIDC discovery successful
INFO     OAuth client ready: <client-id>...
INFO     OAuth initialization complete
```

**BasicAuth mode:**
```
INFO     BasicAuth mode detected (NEXTCLOUD_USERNAME/PASSWORD set)
INFO     Initializing Nextcloud client with BasicAuth
```

---

## Process Management

### Running as a Background Service

Use Docker Compose with `restart: unless-stopped` (see [Docker Compose section](#docker-compose) above).

### Monitoring Logs

```bash
# Docker (find container name first)
docker ps
docker logs -f <container-name>

# Docker Compose
docker-compose logs -f mcp
```

---

## Performance Tuning

### Production Settings

For production deployments, use Docker Compose with the recommended settings:

```yaml
version: '3.8'

services:
  mcp:
    image: ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
    command: --oauth --log-level warning --transport streamable-http
    ports:
      - "127.0.0.1:8000:8000"
    env_file:
      - .env
    volumes:
      - ./data:/app/data
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 512M
```

### Scaling with Multiple Replicas

For higher load, use Docker Swarm or Kubernetes. See the [Helm chart](https://github.com/cbcoutinho/helm-charts) for Kubernetes deployments.

---

## Troubleshooting

### Server won't start

Check logs for errors:
```bash
# View container logs
docker logs <container-name>

# Or run with debug logging
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
  --log-level debug
```

Common issues:
- Environment variables not loaded - Check your `.env` file
- Port already in use - Use a different host port (e.g., `-p 127.0.0.1:8080:8000`)
- OAuth configuration errors - See [Troubleshooting](troubleshooting.md)

### Can't connect to server

1. Verify server is running: `curl http://localhost:8000/health`
2. Check firewall settings
3. Verify host binding (use `0.0.0.0` to allow network access)
4. Check OAuth authentication if enabled

### OAuth authentication fails

See [Troubleshooting OAuth](troubleshooting.md) for detailed OAuth troubleshooting.

---

## See Also

- [Configuration Guide](configuration.md) - Environment variables
- [OAuth Setup](oauth-setup.md) - OAuth authentication setup
- [Troubleshooting](troubleshooting.md) - Common issues and solutions
- [Installation](installation.md) - Installing the server