Nextcloud - A2A | AG-UI | MCP

Version: 0.1.1

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):

nextcloud-agent --transport "stdio"

Run in HTTP mode:

nextcloud-agent --transport "http"  --host "0.0.0.0"  --port "8016"

AI Prompt:

List all files in my 'Documents' folder.

AI Response:

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:

---
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

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-4b-2507)
	--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

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):

nextcloud-agent --transport "stdio"

Run in HTTP mode:

nextcloud-agent --transport "http"  --host "0.0.0.0"  --port "8016"

AI Prompt:

List all files in my 'Documents' folder.

AI Response:

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-4b-2507`
`--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

nextcloud-agent --provider openai --model-id gpt-4 --api-key sk-... --mcp-url http://localhost:8016/mcp

Run with Docker

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

Docker

Build

docker build -t nextcloud-agent .

Run MCP Server

docker run -p 8016:8016 nextcloud-agent

Run A2A Server

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

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:

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:

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:

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:

docker-compose up -d

Configure `mcp.json` for AI Integration

{
  "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

python -m pip install nextcloud-agent

uv pip install nextcloud-agent

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.github/workflows		.github/workflows
nextcloud_agent		nextcloud_agent
.bumpversion.cfg		.bumpversion.cfg
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
compose.yml		compose.yml
debug.Dockerfile		debug.Dockerfile
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

License

Knuckles-Team/nextcloud-agent

Folders and files

Latest commit

History

Repository files navigation

Nextcloud - A2A | AG-UI | MCP

Overview

Supports:

MCP

MCP Tools

Using as an MCP Server

Run in stdio mode (default):

Run in HTTP mode:

A2A Agent

Architecture:

Component Interaction Diagram

Usage

MCP CLI

A2A CLI

Endpoints

Using as an MCP Server

Run in stdio mode (default):

Run in HTTP mode:

Agentic AI

Agent-to-Agent (A2A)

CLI

Examples

Run A2A Server

Run with Docker

Docker

Build

Run MCP Server

Run A2A Server

Deploy MCP Server as a Service

Using Docker Run

Using Docker Compose

Configure mcp.json for AI Integration

Install Python Package

Repository Owners

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Languages

Configure `mcp.json` for AI Integration

Packages