Nextcloud MCP

Nextcloud MCP服务器

一种模型上下文协议（MCP）服务器，与Nextcloud集成，提供对任务、日历、笔记、电子邮件、文件和甲板的访问。支持本地stdio（Claude Desktop）和远程HTTP/SSE传输（Claude Mobile通过Pi或服务器部署）。

特性

任务

• 在所有列表或特定列表中获取任务（按状态筛选：全部/打开/完成）
• 创建具有截止日期和优先级的新任务
• 更新任务（标记完成、更改摘要等）
• 发现所有可用的任务列表

日历

• 通过日期范围筛选获取日历事件
• 创建包含详细信息和位置的新日历事件

备注

• 获取所有笔记
• 使用markdown支持创建新笔记
• 按ID获取特定笔记内容

电子邮件

• 从收件箱获取电子邮件（需要Nextcloud Mail应用程序）

文件（WebDAV）

• 列出包含元数据的文件和文件夹（大小、类型、上次修改时间）
• 读取文本文件内容
• 上传/创建或覆盖文件
• 新建文件夹
• 移动或重命名文件和文件夹

甲板（看板）

• 列出所有板
• 获得全板视图——所有堆栈（列）和带有指定人员和标签的卡片
• 在堆栈中创建卡片
• 更新卡片标题、描述或到期日期
• 在列之间移动卡片

先决条件

1. Nextcloud实例 （任何支持CalDAV的最新版本）
2. 所需Nextcloud应用程序:

- 任务——任务管理 - 日历--活动 - 笔记——记笔记 - 甲板——看板 - 邮件--可选，用于电子邮件访问

1. 应用程序密码：在Nextcloud设置>安全>设备和会话中生成

安装

npm install
npm run build

配置

设置这些环境变量（或将它们放入 .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

⚠️ 始终使用应用程序密码，永远不要使用Nextcloud主密码。

运输方式

stdio（默认）--克劳德桌面，本地

服务器由Claude Desktop作为子进程启动。

添加 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）：

{
  "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或服务器部署

集 MCP_TRANSPORT=http 服务器监听 MCP_PORT （默认值 3000).

终点：

• GET /sse --SSE连接
• POST /messages?sessionId=… --入站消息
• GET /health --健康检查（无需身份验证）

systemd服务

创建 /etc/systemd/system/nextcloud-mcp.service:

[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

sudo systemctl enable --now nextcloud-mcp

Apache反向代理

将位置块添加到现有的SSL vhost。SSE要求禁用缓冲或事件流停滞。

    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

如果所需模块尚未激活，请启用：

sudo a2enmod proxy proxy_http
sudo systemctl reload apache2

连接客户端

克劳德桌面 （本地局域网，无需Apache）：

{
  "mcpServers": {
    "nextcloud": {
      "url": "http://raspberrypi.local:3000/sse",
      "headers": { "Authorization": "Bearer your-secret-token" }
    }
  }
}

克劳德·莫比尔 （通过Apache/HTTPS）：

在Claude应用程序中添加为远程集成：

URL:           https://yourdomain.com/mcp/sse
Authorization: Bearer your-secret-token

可用工具

任务

日历

备注

电子邮件

文件

甲板

示例提示

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

故障排除

连接问题

• 对Nextcloud URL使用HTTPS，没有尾随斜线
• 验证应用程序密码是否正确
• 确保在Nextcloud中安装了所需的应用程序

SSE流无法通过Apache工作

• 确认 proxy_http 模块已启用
• 确保 ProxyBuffering off 已设置--如果没有此设置，事件将被缓冲，客户端似乎会挂起

牌组卡未显示

• get_deck_board 在单独的请求中从板中获取堆栈——确保安装了Deck应用程序并且板ID正确

CalDAV问题

• 任务列表和日历名称区分大小写，必须与Nextcloud设置匹配
• 默认日历为 personal；使用 get_task_lists 发现列表ID

电子邮件问题

• 必须安装Nextcloud Mail应用程序，并至少配置一个帐户
• 帐户ID默认为 0 （第一个账户）

调试日志

• macOS： ~/Library/Logs/Claude/mcp*.log
• HTTP模式：systemd服务的stdout/stderr(journalctl -u nextcloud-mcp -f)

安全

• 始终使用应用程序密码，永远不要使用Nextcloud主密码
• 集 MCP_AUTH_TOKEN 只要服务器可以通过网络访问
• 使用HTTPS（通过现有的Apache SSL vhost）进行面向互联网的部署
• 将凭据存储在环境变量或systemd单元文件中，而不是代码中

使用的API端点

• CalDAV： /remote.php/dav/calendars/{username}/
• WebDAV： /remote.php/dav/files/{username}/
• 笔记： /index.php/apps/notes/api/v1/
• 邮件： /index.php/apps/mail/api/
• 甲板： /ocs/v2.php/apps/deck/api/v1.0/

许可证

麻省理工学院