nextcloud-agent 0.2.14
Nextcloud MCP Server for Agentic AI!
License: MIT
Requires Python: >=3.10

# Nextcloud - A2A | AG-UI | MCP

![PyPI - Version](https://img.shields.io/pypi/v/nextcloud-agent)
![MCP Server](https://badge.mcpx.dev?type=server 'MCP Server')
![PyPI - Downloads](https://img.shields.io/pypi/dd/nextcloud-agent)
![GitHub Repo stars](https://img.shields.io/github/stars/Knuckles-Team/nextcloud-agent)
![GitHub forks](https://img.shields.io/github/forks/Knuckles-Team/nextcloud-agent)
![GitHub contributors](https://img.shields.io/github/contributors/Knuckles-Team/nextcloud-agent)
![PyPI - License](https://img.shields.io/pypi/l/nextcloud-agent)
![GitHub](https://img.shields.io/github/license/Knuckles-Team/nextcloud-agent)

![GitHub last commit (by committer)](https://img.shields.io/github/last-commit/Knuckles-Team/nextcloud-agent)
![GitHub pull requests](https://img.shields.io/github/issues-pr/Knuckles-Team/nextcloud-agent)
![GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed/Knuckles-Team/nextcloud-agent)
![GitHub issues](https://img.shields.io/github/issues/Knuckles-Team/nextcloud-agent)

![GitHub top language](https://img.shields.io/github/languages/top/Knuckles-Team/nextcloud-agent)
![GitHub language count](https://img.shields.io/github/languages/count/Knuckles-Team/nextcloud-agent)
![GitHub repo size](https://img.shields.io/github/repo-size/Knuckles-Team/nextcloud-agent)
![GitHub repo file count (file type)](https://img.shields.io/github/directory-file-count/Knuckles-Team/nextcloud-agent)
![PyPI - Wheel](https://img.shields.io/pypi/wheel/nextcloud-agent)
![PyPI - Implementation](https://img.shields.io/pypi/implementation/nextcloud-agent)

*Version: 0.2.14*

## Overview

Nextcloud MCP Server + A2A Server

It includes a Model Context Protocol (MCP) server and an out of the box Agent2Agent (A2A) agent

Interacts with your self-hosted Nextcloud instance to manage files, calendars, contacts, and sharing through an MCP server!

This repository is actively maintained - Contributions are welcome!

### Supports:
- **File Operations**: List, Read, Write, Move, Copy, Delete, Create Folder, Get Properties
- **Sharing**: List Shares, Create Share, Delete Share
- **Calendars**: List Calendars, List Events, Create Event
- **Contacts**: List Address Books, List Contacts, Create Contact
- **User Info**: Get current user details

## MCP

### MCP Tools

| Function Name | Description | Tag(s) |
|:---|:---|:---|
| `list_files` | List files and directories at a specific path. | `files` |
| `read_file` | Read the contents of a text file. | `files` |
| `write_file` | Write text content to a file. | `files` |
| `create_folder` | Create a new directory. | `files` |
| `delete_item` | Delete a file or directory. | `files` |
| `move_item` | Move a file or directory. | `files` |
| `copy_item` | Copy a file or directory. | `files` |
| `get_properties` | Get detailed properties for a file or folder. | `files` |
| `list_shares` | List all shares. | `sharing` |
| `create_share` | Create a new share (User, Group, Link, Email). | `sharing` |
| `delete_share` | Delete a share. | `sharing` |
| `list_calendars` | List available calendars. | `calendar` |
| `list_calendar_events` | List events in a calendar. | `calendar` |
| `create_calendar_event` | Create a calendar event. | `calendar` |
| `list_address_books` | List address books. | `contacts` |
| `list_contacts` | List contacts in an address book. | `contacts` |
| `create_contact` | Create a new contact. | `contacts` |
| `get_user_info` | Get information about the current user. | `user` |


### Using as an MCP Server

The MCP Server can be run in two modes: `stdio` (for local testing) or `http` (for networked access). To start the server, use the following commands:

#### Run in stdio mode (default):
```bash
nextcloud-agent --transport "stdio"
```

#### Run in HTTP mode:
```bash
nextcloud-agent --transport "http"  --host "0.0.0.0"  --port "8016"
```

AI Prompt:
```text
List all files in my 'Documents' folder.
```

AI Response:
```text
Contents of 'Documents':
[FILE] Project_Proposal.docx (Size: 15403, Modified: Sun, 01 Feb 2026 10:00:00 GMT)
[FILE] Notes.txt (Size: 450, Modified: Sun, 01 Feb 2026 09:30:00 GMT)
[DIR] Financials (Size: -, Modified: Fri, 30 Jan 2026 14:20:00 GMT)
```

## A2A Agent

This package also includes an A2A agent server that can be used to interact with the Nextcloud MCP server.

### Architecture:

```mermaid
---
config:
  layout: dagre
---
flowchart TB
 subgraph subGraph0["Agent Capabilities"]
        C["Agent"]
        B["A2A Server - Uvicorn/FastAPI"]
        D["MCP Tools"]
        F["Agent Skills"]
  end
    C --> D & F
    A["User Query"] --> B
    B --> C
    D --> E["Nextcloud API"]

     C:::agent
     B:::server
     A:::server
    classDef server fill:#f9f,stroke:#333
    classDef agent fill:#bbf,stroke:#333,stroke-width:2px
    style B stroke:#000000,fill:#FFD600
    style D stroke:#000000,fill:#BBDEFB
    style F fill:#BBDEFB
    style A fill:#C8E6C9
    style subGraph0 fill:#FFF9C4
```

### Component Interaction Diagram

```mermaid
sequenceDiagram
    participant User
    participant Server as A2A Server
    participant Agent as Agent
    participant Skill as Agent Skills
    participant MCP as MCP Tools

    User->>Server: Send Query
    Server->>Agent: Invoke Agent
    Agent->>Skill: Analyze Skills Available
    Skill->>Agent: Provide Guidance on Next Steps
    Agent->>MCP: Invoke Tool
    MCP-->>Agent: Tool Response Returned
    Agent-->>Agent: Return Results Summarized
    Agent-->>Server: Final Response
    Server-->>User: Output
```

## Usage

### MCP CLI

| Short Flag | Long Flag                          | Description                                                                 |
|------------|------------------------------------|-----------------------------------------------------------------------------|
| -h         | --help                             | Display help information                                                    |
| -t         | --transport                        | Transport method: 'stdio', 'http', or 'sse' [legacy] (default: stdio)       |
| -s         | --host                             | Host address for HTTP transport (default: 0.0.0.0)                          |
| -p         | --port                             | Port number for HTTP transport (default: 8016)                              |
|            | --auth-type                        | Authentication type: 'none', 'static', 'jwt', 'oauth-proxy', 'oidc-proxy', 'remote-oauth' (default: none) |
|            | --token-jwks-uri                   | JWKS URI for JWT verification                                              |
|            | --token-issuer                     | Issuer for JWT verification                                                |
|            | --token-audience                   | Audience for JWT verification                                              |
|            | --oauth-upstream-auth-endpoint     | Upstream authorization endpoint for OAuth Proxy                             |
|            | --oauth-upstream-token-endpoint    | Upstream token endpoint for OAuth Proxy                                    |
|            | --oauth-upstream-client-id         | Upstream client ID for OAuth Proxy                                         |
|            | --oauth-upstream-client-secret     | Upstream client secret for OAuth Proxy                                     |
|            | --oauth-base-url                   | Base URL for OAuth Proxy                                                   |
|            | --oidc-config-url                  | OIDC configuration URL                                                     |
|            | --oidc-client-id                   | OIDC client ID                                                             |
|            | --oidc-client-secret               | OIDC client secret                                                         |
|            | --oidc-base-url                    | Base URL for OIDC Proxy                                                    |
|            | --remote-auth-servers              | Comma-separated list of authorization servers for Remote OAuth             |
|            | --remote-base-url                  | Base URL for Remote OAuth                                                  |
|            | --allowed-client-redirect-uris     | Comma-separated list of allowed client redirect URIs                       |
|            | --eunomia-type                     | Eunomia authorization type: 'none', 'embedded', 'remote' (default: none)   |
|            | --eunomia-policy-file              | Policy file for embedded Eunomia (default: mcp_policies.json)              |
|            | --eunomia-remote-url               | URL for remote Eunomia server                                              |


### A2A CLI
#### Endpoints
- **Web UI**: `http://localhost:9016/` (if enabled)
- **A2A**: `http://localhost:9016/a2a` (Discovery: `/a2a/.well-known/agent.json`)
- **AG-UI**: `http://localhost:9016/ag-ui` (POST)

| Short Flag | Long Flag         | Description                                                            |
|------------|-------------------|------------------------------------------------------------------------|
| -h         | --help            | Display help information                                               |
|            | --host            | Host to bind the server to (default: 0.0.0.0)                          |
|            | --port            | Port to bind the server to (default: 9016)                             |
|            | --reload          | Enable auto-reload                                                     |
|            | --provider        | LLM Provider: 'openai', 'anthropic', 'google', 'huggingface'           |
|            | --model-id        | LLM Model ID (default: qwen/qwen3-coder-next)                                  |
|            | --base-url        | LLM Base URL (for OpenAI compatible providers)                         |
|            | --api-key         | LLM API Key                                                            |
|            | --mcp-url         | MCP Server URL (default: http://localhost:8016/mcp)                    |
|            | --web             | Enable Pydantic AI Web UI                                              | False (Env: ENABLE_WEB_UI) |


### Using as an MCP Server
The MCP Server can be run in two modes: `stdio` (for local testing) or `http` (for networked access). To start the server, use the following commands:

#### Run in stdio mode (default):
```bash
nextcloud-agent --transport "stdio"
```

#### Run in HTTP mode:
```bash
nextcloud-agent --transport "http"  --host "0.0.0.0"  --port "8016"
```

AI Prompt:
```text
List all files in my 'Documents' folder.
```

AI Response:
```text
Contents of 'Documents':
[FILE] Project_Proposal.docx (Size: 15403, Modified: Sun, 01 Feb 2026 10:00:00 GMT)
[FILE] Notes.txt (Size: 450, Modified: Sun, 01 Feb 2026 09:30:00 GMT)
[DIR] Financials (Size: -, Modified: Fri, 30 Jan 2026 14:20:00 GMT)
```

### Agentic AI
`nextcloud-agent` is designed to be used by Agentic AI systems. It provides a set of tools that allow agents to manage Nextcloud resources.

## Agent-to-Agent (A2A)

This package also includes an A2A agent server that can be used to interact with the Nextcloud MCP server.

### CLI

| Argument          | Description                                                    | Default                        |
|-------------------|----------------------------------------------------------------|--------------------------------|
| `--host`          | Host to bind the server to                                     | `0.0.0.0`                      |
| `--port`          | Port to bind the server to                                     | `9016`                         |
| `--reload`        | Enable auto-reload                                             | `False`                        |
| `--provider`      | LLM Provider (openai, anthropic, google, huggingface)          | `openai`                       |
| `--model-id`      | LLM Model ID                                                   | `qwen/qwen3-coder-next`                |
| `--base-url`      | LLM Base URL (for OpenAI compatible providers)                 | `http://ollama.arpa/v1`        |
| `--api-key`       | LLM API Key                                                    | `ollama`                       |
| `--mcp-url`       | MCP Server URL                                                 | `http://nextcloud-mcp:8016/mcp`  |
| `--allowed-tools` | List of allowed MCP tools                                      | `list_files`, `...`            |

### Examples

#### Run A2A Server
```bash
nextcloud-agent --provider openai --model-id gpt-4 --api-key sk-... --mcp-url http://localhost:8016/mcp
```

#### Run with Docker
```bash
docker run -e CMD=nextcloud-agent -p 9016:9016 nextcloud-agent
```

## Docker

### Build

```bash
docker build -t nextcloud-agent .
```

### Run MCP Server

```bash
docker run -p 8016:8016 nextcloud-agent
```

### Run A2A Server

```bash
docker run -e CMD=nextcloud-agent -p 9016:9016 nextcloud-agent
```

### Deploy MCP Server as a Service

The Nextcloud MCP server can be deployed using Docker, with configurable authentication, middleware, and Eunomia authorization.

#### Using Docker Run

```bash
docker pull knucklessg1/nextcloud-agent:latest

docker run -d \
  --name nextcloud-agent \
  -p 8016:8016 \
  -e HOST=0.0.0.0 \
  -e PORT=8016 \
  -e TRANSPORT=http \
  -e AUTH_TYPE=none \
  -e EUNOMIA_TYPE=none \
  -e NEXTCLOUD_BASE_URL=https://cloud.example.com \
  -e NEXTCLOUD_USERNAME=user \
  -e NEXTCLOUD_PASSWORD=pass \
  knucklessg1/nextcloud-agent:latest
```

For advanced authentication (e.g., JWT, OAuth Proxy, OIDC Proxy, Remote OAuth) or Eunomia, add the relevant environment variables:

```bash
docker run -d \
  --name nextcloud-agent \
  -p 8016:8016 \
  -e HOST=0.0.0.0 \
  -e PORT=8016 \
  -e TRANSPORT=http \
  -e AUTH_TYPE=oidc-proxy \
  -e OIDC_CONFIG_URL=https://provider.com/.well-known/openid-configuration \
  -e OIDC_CLIENT_ID=your-client-id \
  -e OIDC_CLIENT_SECRET=your-client-secret \
  -e OIDC_BASE_URL=https://your-server.com \
  -e ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,https://*.example.com/* \
  -e EUNOMIA_TYPE=embedded \
  -e EUNOMIA_POLICY_FILE=/app/mcp_policies.json \
  -e NEXTCLOUD_BASE_URL=https://cloud.example.com \
  -e NEXTCLOUD_USERNAME=user \
  -e NEXTCLOUD_PASSWORD=pass \
  knucklessg1/nextcloud-agent:latest
```

#### Using Docker Compose

Create a `docker-compose.yml` file:

```yaml
services:
  nextcloud-mcp:
    image: knucklessg1/nextcloud-agent:latest
    environment:
      - HOST=0.0.0.0
      - PORT=8016
      - TRANSPORT=http
      - AUTH_TYPE=none
      - EUNOMIA_TYPE=none
      - NEXTCLOUD_BASE_URL=https://cloud.example.com
      - NEXTCLOUD_USERNAME=user
      - NEXTCLOUD_PASSWORD=pass
    ports:
      - 8016:8016
```

For advanced setups with authentication and Eunomia:

```yaml
services:
  nextcloud-mcp:
    image: knucklessg1/nextcloud-agent:latest
    environment:
      - HOST=0.0.0.0
      - PORT=8016
      - TRANSPORT=http
      - AUTH_TYPE=oidc-proxy
      - OIDC_CONFIG_URL=https://provider.com/.well-known/openid-configuration
      - OIDC_CLIENT_ID=your-client-id
      - OIDC_CLIENT_SECRET=your-client-secret
      - OIDC_BASE_URL=https://your-server.com
      - ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,https://*.example.com/*
      - EUNOMIA_TYPE=embedded
      - EUNOMIA_POLICY_FILE=/app/mcp_policies.json
      - NEXTCLOUD_BASE_URL=https://cloud.example.com
      - NEXTCLOUD_USERNAME=user
      - NEXTCLOUD_PASSWORD=pass
    ports:
      - 8016:8016
    volumes:
      - ./mcp_policies.json:/app/mcp_policies.json
```

Run the service:

```bash
docker-compose up -d
```

#### Configure `mcp.json` for AI Integration

```json
{
  "mcpServers": {
    "nextcloud": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "nextcloud-agent"
      ],
      "env": {
        "NEXTCLOUD_BASE_URL": "https://cloud.example.com",
        "NEXTCLOUD_USERNAME": "user",
        "NEXTCLOUD_PASSWORD": "pass"
      },
      "timeout": 300000
    }
  }
}
```

## Install Python Package

```bash
python -m pip install nextcloud-agent
```
```bash
uv pip install nextcloud-agent
```

## Repository Owners

<img width="100%" height="180em" src="https://github-readme-stats.vercel.app/api?username=Knucklessg1&show_icons=true&hide_border=true&&count_private=true&include_all_commits=true" />

![GitHub followers](https://img.shields.io/github/followers/Knucklessg1)
![GitHub User's stars](https://img.shields.io/github/stars/Knucklessg1)