动态MCP服务器

Nextcloud动态MCP服务器

此服务器将一个实时Nextcloud实例作为MCP服务器公开，可灵活安装所有应用程序。

它查询Nextcloud，而不是发送固定的工具列表 ocs_api_viewer 应用程序启动时，读取已安装应用程序的OpenAPI描述，并将这些操作动态转换为MCP工具。结果是一个MCP端点，它反映了连接的Nextcloud实例上可用的API。

服务器做什么

• 连接到由定义的Nextcloud实例 NEXTCLOUD_URL
• 在启动时使用服务器发现凭据，并在执行工具时使用每个请求的凭据
• 从以下位置读取已安装的应用程序API NEXTCLOUD_URL/apps/ocs_api_viewer
• 根据发现的OpenAPI操作动态创建MCP工具
• 代理工具回调到真正的Nextcloud REST端点
• 支持两者 streamable-http 和 stdio MCP传输

一个内置工具始终可用：

• nextcloud_discovery_status：返回连接的Nextcloud URL、身份验证模式、发现的应用程序、工具计数和上次刷新/错误状态

动态工具由Nextcloud应用程序id加上OpenAPI操作id或路径命名，例如：

files_sharing_get_shares
provisioning_api_create_user
dav_upcoming_events_get_events

主要服务端点

GET /

健康和发现端点。退货：

• 服务器名称
• 运输方式
• MCP路径
• 是否配置了默认凭据
• 当前发现状态

例子：

curl http://localhost:8000/

/mcp

主MCP端点 streamable-http 客户。

Point Codex、Claude Code或任何其他MCP客户：

http://localhost:8000/mcp

需求

• Docker和Docker Compose
• 可访问的Nextcloud实例
• Nextcloud ocs_api_viewer 该实例上已启用应用程序
• Nextcloud用户名和应用令牌，有权访问您要公开的API

配置

服务器完全配置了环境变量。

身份验证模式

服务器支持两种身份验证模式：

1. 通过以下方式进行服务器级发现身份验证 NEXTCLOUD_USERNAME 和 NEXTCLOUD_APP_TOKEN
2. 通过MCP请求头进行每次请求认证：
   • X-Nextcloud-Username
   • X-Nextcloud-AppToken

服务器级凭据仅在启动发现期间使用。每个实际的工具调用都必须提供请求头，服务器不会回退到启动管理员凭据来执行。

如何启动服务器

使用您的Nextcloud URL和凭据更新docker-compose.yml，然后运行：

docker compose up -d --build

服务器将在以下位置可用：

http://localhost:8000/
http://localhost:8000/mcp

Discovery的工作原理

启动时，服务器：

1. 呼叫 GET /apps/ocs_api_viewer/apps 在已配置的Nextcloud实例上
2. 从以下位置加载每个应用程序的OpenAPI文档 GET /apps/ocs_api_viewer/apps/{appId}
3. 根据操作参数和请求体构建MCP输入模式
4. 将操作注册为可调用的MCP工具

Discovery使用服务器的默认值 NEXTCLOUD_USERNAME 和 NEXTCLOUD_APP_TOKEN.

每次工具执行仅使用 X-Nextcloud-Username 和 X-Nextcloud-AppToken。如果缺少这些标头，则工具调用将被拒绝，而不是退回到启动管理员帐户。

如果发现失败，服务器仍将启动并通过报告错误 nextcloud_discovery_status 和 GET /.

客户端配置示例

法典

Codex可以将Nextcloud凭据作为HTTP标头传递：

codex mcp add nextcloud-live --url http://localhost:8000/mcp

等效 ~/.codex/config.toml 例子：

[mcp_servers.nextcloud-live]
url = "http://localhost:8000/mcp"
http_headers = { X-Nextcloud-Username = "NEXTCLOUD_USERNAME", X-Nextcloud-AppToken = "NEXTCLOUD_APP_TOKEN" }

克劳德代码

CLI示例：

claude mcp add --transport http nextcloud-live http://localhost:8000/mcp

项目范围 .mcp.json 使用环境变量中的每个用户凭据的示例：

{
  "mcpServers": {
    "nextcloud-live": {
      "type": "http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-Nextcloud-Username": "${NEXTCLOUD_USERNAME}",
        "X-Nextcloud-AppToken": "${NEXTCLOUD_APP_TOKEN}"
      }
    }
  }
}

当您想要一个共享的MCP服务器URL，但每个开发人员都应该使用自己的帐户向Nextcloud进行身份验证时，这很有用。

烟雾检查示例

检查HTTP运行状况终结点：

curl http://localhost:8000/

如果你正在使用Docker Compose：

docker compose logs -f mcp

在MCP客户端中，调用：

• nextcloud_discovery_status

然后验证发现的工具列表是否包括您启用的Nextcloud应用程序的操作。