Metadata-Version: 2.5
Name: nextcloud-mcp-lite
Version: 0.4.2
Summary: Minimal, high-performance MCP server for Nextcloud file sync, search, and PIM
License: MIT
Keywords: ai,caldav,mcp,model-context-protocol,nextcloud,webdav
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: httpx<0.29,>=0.28.1
Requires-Dist: icalendar<7.4,>=7.3.0
Requires-Dist: mcp[cli]<3,>=2.1
Requires-Dist: uvicorn>=0.30.0
Description-Content-Type: text/markdown

# nextcloud-mcp-lite

Minimal, high-performance Model Context Protocol (MCP) server for Nextcloud file sync, search, and PIM (Calendar & Tasks).

Designed for seamless execution via `uv tool run` or `uvx`, with zero heavy dependencies, instant startup (<0.3s), and low memory footprint (<30 MB).

## Tool Suite (11 Tools)

### 📁 Files & Search (WebDAV)
- **`list_files`**: List directory contents (Depth: 1) with clean paths, file sizes, MIME types, modification dates, and `file_id`.
- **`read_file`**: Read file contents with socket-level streaming up to `max_bytes` (returns UTF-8 text or Base64).
- **`write_file`**: Create or overwrite files with auto-parent folder creation (`mkdir -p`) and optional ETag concurrency guard.
- **`file_action`**: Consolidated file manager for simple actions:
  - `action="create_dir"`: Create directory with parent creation.
  - `action="delete"`: Delete file or directory permanently.
  - `action="move"`: Move file or directory to destination.
  - `action="copy"`: Copy file or directory to destination.
  - `action="rename"`: Rename file or directory in place.
- **`search_files`**: Fast server-side indexed search using RFC 5323 WebDAV `SEARCH` (DASL). Searches across the entire storage tree by name pattern (wildcards supported), MIME type, or favorites without recursion limits.
- **`file_comment`**: Read and manage file comments (`list`, `create`, `update`, `delete`).

### 📅 Calendar & Tasks (CalDAV)
- **`list_calendars`**: List all user calendars and task lists with display names, colors, and CalDAV paths.
- **`list_events`**: Dedicated read-only agenda/event query. Filter by `start_date`, `end_date`, `calendar_path`, and `limit`.
- **`manage_event`**: Event lifecycle management (`create`, `get`, `update`, `delete`). Supports recurrence rules (`rrule`), status, location, and description.
- **`list_todos`**: Dedicated read-only task query. Filter by status (`pending`, `completed`, `all`) and `calendar_path`.
- **`manage_todo`**: Task lifecycle management (`create`, `get`, `update`, `complete`, `delete`). Supports priorities (`0-9`), due dates, and notes.

---

## Installation & Running

### Using `uv` (Recommended)

No manual installation required:

```bash
uvx nextcloud-mcp-lite
# or
uv tool run nextcloud-mcp-lite
```

### Using `pip`

```bash
pip install nextcloud-mcp-lite
nextcloud-mcp-lite
```

---

## Configuration

Set the following environment variables:

| Variable | Description | Default |
| :--- | :--- | :--- |
| `NEXTCLOUD_HOST` | URL of your Nextcloud instance (e.g. `https://cloud.example.com`) | *Required* |
| `NEXTCLOUD_USERNAME` | Your Nextcloud username | *Required* |
| `NEXTCLOUD_PASSWORD` | App password from Nextcloud *Settings > Security > Devices & sessions* | *Required* |
| `NEXTCLOUD_VERIFY_SSL` | Verify SSL certificates (`true`/`false`) | `true` |

---

## MCP Client Setup

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "nextcloud": {
      "command": "uvx",
      "args": ["nextcloud-mcp-lite"],
      "env": {
        "NEXTCLOUD_HOST": "https://cloud.example.com",
        "NEXTCLOUD_USERNAME": "your_username",
        "NEXTCLOUD_PASSWORD": "your_app_password"
      }
    }
  }
}
```

### Claude Code / Gemini CLI / Terminal

```bash
NEXTCLOUD_HOST="https://cloud.example.com" \
NEXTCLOUD_USERNAME="your_username" \
NEXTCLOUD_PASSWORD="your_app_password" \
uvx nextcloud-mcp-lite
```

### HTTP / SSE Transport

For remote MCP clients:

```bash
nextcloud-mcp-lite --transport streamable-http --host 0.0.0.0 --port 8000
```

---

## License

MIT
