# Nextcloud MCP Server

A Model Context Protocol (MCP) server that integrates with Nextcloud to provide access to tasks, calendar, notes, email, files, and Deck boards. Supports both local stdio (Claude Desktop) and remote HTTP/SSE transport (Claude Mobile via a Pi or server deployment).

## Features

### Tasks
- Get tasks across all lists or a specific list (filter by status: all/open/completed)
- Create new tasks with due dates and priorities
- Update tasks (mark complete, change summary, etc.)
- Discover all available task lists

### Calendar
- Get calendar events with date range filtering
- Create new calendar events with details and location

### Notes
- Get all notes
- Create new notes with markdown support
- Get specific note content by ID

### Email
- Get emails from inbox (requires Nextcloud Mail app)

### Files (WebDAV)
- List files and folders with metadata (size, type, last modified)
- Read text file content
- Upload / create or overwrite files
- Create folders
- Move or rename files and folders

### Deck (Kanban)
- List all boards
- Get a full board view — all stacks (columns) and cards with assignees and labels
- Create cards in a stack
- Update card title, description, or due date
- Move cards between columns

## Prerequisites

1. **Nextcloud instance** (any recent version with CalDAV support)
2. **Required Nextcloud apps**:
   - Tasks — task management
   - Calendar — events
   - Notes — note-taking
   - Deck — Kanban boards
   - Mail — optional, for email access
3. **App password**: generate in Nextcloud Settings > Security > Devices & sessions

## Installation

```bash
npm install
npm run build
```

## Configuration

Set these environment variables (or put them in a `.env` file for local dev):

```env
NEXTCLOUD_URL=https://your-nextcloud.com
NEXTCLOUD_USERNAME=your-username
NEXTCLOUD_PASSWORD=your-app-password

# HTTP/SSE mode (omit for stdio)
MCP_TRANSPORT=http
MCP_PORT=3000
MCP_AUTH_TOKEN=your-secret-token
```

⚠️ Always use an app password, never your main Nextcloud password.

## Transport modes

### stdio (default) — Claude Desktop, local

The server is launched as a subprocess by Claude Desktop.

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "nextcloud": {
      "command": "node",
      "args": ["/path/to/nextcloud-mcp/build/index.js"],
      "env": {
        "NEXTCLOUD_URL": "https://your-nextcloud.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_PASSWORD": "your-app-password"
      }
    }
  }
}
```

### HTTP/SSE — Raspberry Pi or server deployment

Set `MCP_TRANSPORT=http` and the server listens on `MCP_PORT` (default `3000`).

Endpoints:
- `GET /sse` — SSE connection
- `POST /messages?sessionId=…` — inbound messages
- `GET /health` — health check (no auth required)

#### systemd service

Create `/etc/systemd/system/nextcloud-mcp.service`:

```ini
[Unit]
Description=Nextcloud MCP Server
After=network.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/nextcloud-mcp
ExecStart=/usr/bin/node build/index.js
Restart=on-failure
Environment=MCP_TRANSPORT=http
Environment=MCP_PORT=3000
Environment=MCP_AUTH_TOKEN=your-secret-token
Environment=NEXTCLOUD_URL=https://your-nextcloud.com
Environment=NEXTCLOUD_USERNAME=your-username
Environment=NEXTCLOUD_PASSWORD=your-app-password

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl enable --now nextcloud-mcp
```

#### Apache reverse proxy

Add a location block to your existing SSL vhost. SSE requires buffering to be disabled or the event stream stalls.

```apache
<Location /mcp/>
    ProxyPass        http://localhost:3000/ flushpackets=on
    ProxyPassReverse http://localhost:3000/

    # Required for SSE — flush packets immediately rather than buffering
    SetEnv           proxy-nokeepalive 1
    SetEnv           proxy-initial-not-buffered 1
</Location>
```

Enable the required modules if not already active:

```bash
sudo a2enmod proxy proxy_http
sudo systemctl reload apache2
```

#### Connecting clients

**Claude Desktop** (local LAN, no Apache needed):
```json
{
  "mcpServers": {
    "nextcloud": {
      "url": "http://raspberrypi.local:3000/sse",
      "headers": { "Authorization": "Bearer your-secret-token" }
    }
  }
}
```

**Claude Mobile** (via Apache/HTTPS):

Add as a remote integration in the Claude app:
```
URL:           https://yourdomain.com/mcp/sse
Authorization: Bearer your-secret-token
```

## Available tools

### Tasks
| Tool | Description |
|------|-------------|
| `get_task_lists` | Discover all VTODO-capable lists |
| `get_tasks` | Retrieve tasks; filter by list, status, limit |
| `create_task` | Create task with summary, description, due date, priority |
| `update_task` | Update status, summary, or percent complete |

### Calendar
| Tool | Description |
|------|-------------|
| `get_calendar_events` | Get events in a date range |
| `create_calendar_event` | Create event with title, times, description, location |

### Notes
| Tool | Description |
|------|-------------|
| `get_notes` | List all notes |
| `create_note` | Create note with title, content, category |
| `get_note_content` | Get full content of a note by ID |

### Email
| Tool | Description |
|------|-------------|
| `get_emails` | Get recent inbox emails |

### Files
| Tool | Description |
|------|-------------|
| `list_files` | List folder contents with metadata |
| `get_file` | Read a text file's content |
| `upload_file` | Create or overwrite a file |
| `create_folder` | Create a new directory |
| `move_file` | Move or rename a file or folder |

### Deck
| Tool | Description |
|------|-------------|
| `get_deck_boards` | List all boards |
| `get_deck_board` | Full board view with stacks and cards |
| `create_deck_card` | Add a card to a stack |
| `update_deck_card` | Edit card title, description, or due date |
| `move_deck_card` | Move card to a different column |

## Example prompts

```
"Show me my open tasks"
"Create a task to review the Q4 report, due next Friday"
"What meetings do I have this week?"
"List the files in my Documents folder"
"Read the file Projects/notes.md"
"Show me the boards in Deck"
"Move the 'Fix login bug' card to In Progress"
"What are my latest emails?"
```

## Troubleshooting

**Connection issues**
- Use HTTPS for your Nextcloud URL, no trailing slash
- Verify the app password is correct
- Ensure required apps are installed in Nextcloud

**SSE stream not working through Apache**
- Confirm `proxy_http` module is enabled
- Ensure `ProxyBuffering off` is set — without this, events are buffered and clients appear to hang

**Deck cards not showing**
- `get_deck_board` fetches stacks in a separate request from boards — ensure the Deck app is installed and the board ID is correct

**CalDAV issues**
- Task list and calendar names are case-sensitive and must match your Nextcloud setup
- Default calendar is `personal`; use `get_task_lists` to discover list IDs

**Email issues**
- Nextcloud Mail app must be installed and have at least one account configured
- Account ID defaults to `0` (first account)

**Debug logs**
- macOS: `~/Library/Logs/Claude/mcp*.log`
- HTTP mode: stdout/stderr from the systemd service (`journalctl -u nextcloud-mcp -f`)

## Security

- Always use app passwords, never your main Nextcloud password
- Set `MCP_AUTH_TOKEN` whenever the server is reachable over a network
- Use HTTPS (via your existing Apache SSL vhost) for internet-facing deployments
- Store credentials in environment variables or the systemd unit file, not in code

## API endpoints used

- CalDAV: `/remote.php/dav/calendars/{username}/`
- WebDAV: `/remote.php/dav/files/{username}/`
- Notes: `/index.php/apps/notes/api/v1/`
- Mail: `/index.php/apps/mail/api/`
- Deck: `/ocs/v2.php/apps/deck/api/v1.0/`

## License

MIT