Nextcloud MCP Server

Nextcloud MCP服务器

MCP端点： https://mcp.techmavie.digital/nextcloud/mcp

注： 这个项目是对基于Python的原始TypeScript的完全重写 cbcoutinho/nextcloud mcp服务器，现在与 自托管VPS部署 和 Smithery部署支持. ### 与原始存储库的主要区别： - 语言： 这个项目是用TypeScript编写的，而最初的项目是用Python编写的。 - Smithery支持： 增加了对Smithery部署和通过Smithery游乐场进行本地测试的全面支持。 - 项目结构： 项目结构已针对Node.js/TypeScript环境进行了调整，并集成了MCP SDK。 - 依赖关系： 该项目使用npm进行包管理，而原始项目使用Python的依赖管理工具。 - 部署： 现在支持通过Smithery进行本地开发和云部署。

Nextcloud MCP（模型上下文协议）服务器允许OpenAI的GPT、谷歌的Gemini或Anthropic的Claude等大型语言模型（LLM）与您的Nextcloud实例进行交互。这使得跨Notes、日历、联系人、表和WebDAV文件操作的各种Nextcloud操作能够自动化。

托管HTTP集成现在通过MCP密钥服务支持更安全的多用户流。托管客户端可以使用用户范围的 usr_... 密钥，让服务器在服务器端解析凭据。

特性

该服务器提供与多个Nextcloud应用程序的集成，使LLM能够通过一套全面的 30工具 分为5大类。

支持的Nextcloud应用程序

可用工具（共30个）

📝 笔记工具（5个工具）

📅 日历工具（6个工具）

👥 联系人工具（6个工具）

📊 表格工具（6个工具）

📁 WebDAV文件系统工具（6个工具）

🔍 革命性的统一WebDAV搜索功能

这个MCP服务器的皇冠上的宝石是强大的 统一搜索系统 对于WebDAV文件，灵感来自我创建的另一个MCP上的现代搜索界面： mcp数据管理。这完全改变了您与Nextcloud文件的交互方式，无需指定确切的文件路径。

✨ 主要特点

• 🎯 多范围搜索：同时搜索文件名、文件内容和元数据
• 🧠 智能文件类型检测：自动处理文本文件、代码、配置文件、文档和媒体
• 🔧 高级过滤：按文件类型、大小范围、修改日期和目录筛选
• 📈 智能排名：根据与最近文件和精确匹配的奖金的相关性对结果进行排名
• 👀 内容预览：匹配文本文件的可选内容预览
• ⚡ 性能优化：智能缓存、超时保护和并行处理
• 🛡️ 错误恢复：后备策略可防止超时，并提供有益的建议

🚀 使用示例

// Basic search - find all files containing "FAQ Dean List"
await nextcloud_webdav_search_files({
  query: "FAQ Dean List"
});

// Advanced search - find PDF reports from 2024
await nextcloud_webdav_search_files({
  query: "report 2024",
  fileTypes: ["pdf"],
  searchIn: ["filename", "content"],
  limit: 20,
  includeContent: true,
  quickSearch: true
});

// Directory-specific search with date range
await nextcloud_webdav_search_files({
  query: "meeting notes",
  basePath: "/Documents",
  searchIn: ["filename", "content"],
  dateRange: {
    from: "2024-01-01",
    to: "2024-12-31"
  }
});

// Search by file characteristics
await nextcloud_webdav_search_files({
  query: "configuration files",
  sizeRange: { min: 1024, max: 102400 }, // 1KB - 100KB
  fileTypes: ["json", "yaml", "xml", "conf"]
});

// Quick search for large directories (optimized)
await nextcloud_webdav_search_files({
  query: "budget",
  basePath: "/", // Root directory
  quickSearch: true, // Enables optimizations
  limit: 25,
  maxDepth: 2 // Limit search depth
});

📋 完整的参数参考

🎯 性能提示

• 用于根目录搜索：使用 quickSearch: true 和 maxDepth: 2-3 为了更快的结果
• 对于特定目录：使用 basePath: "/Documents" 而不是搜索根“/”
• 对于大型结果集：添加 fileTypes 过滤以缩小范围
• 对于超时问题：启用 quickSearch 并使用更小的 limit 价值观

🧪 测试工具（1个工具）

🔄 前后对比：搜索革命

统一搜索之前

// You had to know exact paths
await nextcloud_webdav_read_file({
  path: "/Documents/Finance/Reports/Q4_Budget_Analysis_2024.pdf"
});

// Multiple calls needed to explore
await nextcloud_webdav_list_directory({ path: "/" });
await nextcloud_webdav_list_directory({ path: "/Documents" });
await nextcloud_webdav_list_directory({ path: "/Documents/Finance" });
// ... and so on

统一搜索后 ✨

// Natural language search across entire Nextcloud!
await nextcloud_webdav_search_files({
  query: "Q4 budget analysis 2024",
  fileTypes: ["pdf"]
});

// Finds files instantly regardless of location!

🛠️ 高级搜索策略

内容感知搜索

该系统智能地从以下内容中提取和搜索内容：

• 📝 文本文件: .txt, .md, .csv -完整内容索引
• 💻 代码文件: .js, .ts, .py, .html, .css -语法感知搜索
• ⚙️ 配置文件: .json, .xml, .yaml -结构感知索引
• 📄 文件: .pdf, .docx -元数据和属性
• 🎬 媒体文件：图像、视频-EXIF数据和元数据

智能排名系统

使用高级算法对结果进行排名：

1. 文件名完全匹配 → 100 点
2. 文件名中的单词边界 → 80 点
3. 部分文件名匹配 → 60+ 积分（职位奖金）
4. 内容频率匹配 → 50+ 点（项密度）
5. 最近的文件奖励 → +10 积分（过去30天）
6. 文件类型首选项 → +5 点（文本/代码文件）
7. 尺寸方便 → +5 点数（100KB以下的文件）

错误处理和恢复

• 🕐 20秒超时保护 -防止悬挂操作
• 🔄 自动回退搜索 -如果索引失败，则返回目录列表
• 💡 智能建议 -提供有用的优化提示
• 📊 性能指标 -显示搜索持续时间和结果计数

安装

npm快速入门（推荐）

直接从npm安装并作为MCP服务器运行：

# Install globally
npm install -g mcp-nextcloud

# Or install locally in your project
npm install mcp-nextcloud

用作MCP服务器

安装后，您可以直接运行MCP服务器：

# If installed globally
mcp-nextcloud

# If installed locally
npx mcp-nextcloud

# Or using npm script
npm exec mcp-nextcloud

环境设置：创建一个 .env 文件中包含您的Nextcloud凭据：

NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_nextcloud_username
NEXTCLOUD_PASSWORD=your_nextcloud_app_password

与LLM应用程序集成

添加到您的MCP客户端配置中（例如，Claude Desktop、Continue等）：

对于CLI模式（本地、单用户）：

{
  "mcpServers": {
    "nextcloud": {
      "command": "mcp-nextcloud",
      "env": {
        "NEXTCLOUD_HOST": "https://your.nextcloud.instance.com",
        "NEXTCLOUD_USERNAME": "your_username",
        "NEXTCLOUD_PASSWORD": "your_app_password"
      }
    }
  }
}

对于托管HTTP模式（通过MCP密钥服务）：

{
  "mcpServers": {
    "nextcloud": {
      "transport": "streamable-http",
      "url": "https://mcp.techmavie.digital/nextcloud/mcp/usr_XXXXXXXX"
    }
  }
}

推荐给托管客户端： 使用基于路径的URL表单(/mcp/usr_...)用于Claude.ai和类似的托管连接器。保留查询参数表单作为检查器和客户端的兼容性选项，以可靠地保留查询参数。

对于自托管HTTP模式（您自己的服务器）：

{
  "mcpServers": {
    "nextcloud": {
      "transport": "streamable-http",
      "url": "https://mcp.techmavie.digital/nextcloud/mcp",
      "headers": {
        "X-API-Key": "your-server-api-key",
        "X-Nextcloud-Host": "https://your.nextcloud.instance.com",
        "X-Nextcloud-Username": "your_username",
        "X-Nextcloud-Password": "your_app_password"
      }
    }
  }
}

先决条件

• Node.js 18+
• 访问Nextcloud实例
• npm或yarn包管理器

地方发展设置

1. 克隆存储库：

   git clone https://github.com/hithereiamaliff/mcp-nextcloud.git
   cd mcp-nextcloud

1. 安装依赖项：

   npm install

1. 配置您的Nextcloud凭据（请参阅配置部分）

1. 构建项目：

   npm run build

配置

环境变量

创建一个 .env 根目录中的文件基于 .env.sample:

# --- CLI/stdio mode only ---
# These are used when running the server in CLI mode (npm run dev, npm run cli).
# They are NOT used by the HTTP server.
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_nextcloud_username
NEXTCLOUD_PASSWORD=your_nextcloud_app_password

# --- HTTP server: Self-Hosted mode ---
# Required for self-hosted /mcp auth, and also used for /analytics access.
MCP_API_KEY=your-secret-api-key-here

# --- HTTP server: Key Service mode ---
# Set both to enable user api_key=usr_... resolution via the MCP Key Service.
# Users obtain and manage those keys at https://mcpkeys.techmavie.digital
# The MCP server itself talks to the resolver endpoint below.
KEY_SERVICE_URL=https://mcpkeys.techmavie.digital/internal/resolve
KEY_SERVICE_TOKEN=your-key-service-bearer-token

# Optional: Comma-separated list of allowed CORS origins.
ALLOWED_ORIGINS=https://smithery.ai,https://claude.ai

# Optional diagnostics for remote MCP debugging.
# These are intended for temporary troubleshooting in hosted HTTP mode.
MCP_TRACE_HTTP=false
ENABLE_MCP_DIAGNOSTICS=false

# Optional dedicated endpoint for Smithery URL publishing.
ENABLE_SMITHERY_ENDPOINT=false

重要安全注意事项：

• 使用专用的Nextcloud应用程序密码，而不是常规登录密码。在Nextcloud安全设置中生成一个。
• 在HTTP模式下， NEXTCLOUD_* 环境变量是 从未使用自托管客户端通过以下方式提供凭据 X-Nextcloud-* 标头，而关键服务客户端仅发送 usr_... 钥匙。
• 生成一个强大的API密钥： openssl rand -hex 32

Smithery配置

通过Smithery部署时，您可以通过以下方式配置凭据：

• Smithery的URL发布服务器配置界面

对于Smithery，推荐的模型是：

• 用户输入 nextcloudHost, nextcloudUsername，以及 nextcloudPassword 直接
• Smithery将这些价值观转发给 /smithery/mcp 端点作为标头
• 主办 usr_... 关键服务流保持独立，并继续使用 /mcp/usr_...

部署和使用

选项1：托管服务器（推荐）

使用此MCP服务器的最简单方法是通过托管端点。 无需安装！

端点： https://mcp.techmavie.digital/nextcloud/mcp

认证

托管服务器使用 MCP密钥服务 用于身份验证。您获得了个人API密钥(usr_XXXXXXXX)从MCP密钥服务门户：

https://mcpkeys.techmavie.digital

然后，服务器会在幕后通过解析器端点自动解析您的Nextcloud凭据。

为什么这比旧的查询凭据方法更安全：

• 连接器URL中未嵌入原始Nextcloud凭据
• 撤销a usr_... 密钥比到处旋转用户的底层Nextcloud密码更容易
• 服务器端审计和策略更容易集中
• 支持/调试工作流更安全，因为用户共享一个作用域密钥，而不是他们真正的Nextcloud密码

Claude.ai/托管连接器URL（推荐）：

https://mcp.techmavie.digital/nextcloud/mcp/usr_XXXXXXXX

正确保留查询参数的客户端的替代URL：

https://mcp.techmavie.digital/nextcloud/mcp?api_key=usr_XXXXXXXX

客户端配置

{
  "mcpServers": {
    "nextcloud": {
      "transport": "streamable-http",
      "url": "https://mcp.techmavie.digital/nextcloud/mcp/usr_XXXXXXXX"
    }
  }
}

使用MCP检查员进行测试

npx @modelcontextprotocol/inspector
# Select "Streamable HTTP"
# Enter URL: https://mcp.techmavie.digital/nextcloud/mcp/usr_XXXXXXXX

选项2：自托管（VPS）

如果你更喜欢运行自己的实例，内置的Docker+Nginx设置是：

# Set required environment variables
export MCP_API_KEY=your-secret-api-key  # Required for self-hosted /mcp auth and /analytics
export KEY_SERVICE_URL=https://mcpkeys.techmavie.digital/internal/resolve  # Optional: enables key service mode
export KEY_SERVICE_TOKEN=your-key-service-bearer-token                      # Optional: enables key service mode

# Using Docker
docker compose up -d --build

# Or run directly
npm run build
npm run start:http

推荐的VPS设置

1. 将仓库克隆到您的服务器上：

   git clone https://github.com/hithereiamaliff/mcp-nextcloud.git
   cd mcp-nextcloud

1. 创建一个 .env 使用服务器设置的文件：

   MCP_API_KEY=your-secret-api-key
   KEY_SERVICE_URL=https://mcpkeys.techmavie.digital/internal/resolve
   KEY_SERVICE_TOKEN=your-key-service-bearer-token
   ALLOWED_ORIGINS=https://smithery.ai,https://claude.ai
   ENABLE_SMITHERY_ENDPOINT=false

笔记： - 使用 KEY_SERVICE_URL + KEY_SERVICE_TOKEN 只有当你想要托管风格时 usr_... 关键分辨率。 - 用户通过以下方式获取和管理这些密钥 https://mcpkeys.techmavie.digital. - MCP服务器本身应继续使用解析器端点路径，而不是门户主页。 - 集 ENABLE_SMITHERY_ENDPOINT=true 仅当您想发布专用的Smithery直接凭据端点时。

1. 启动容器：

   docker compose up -d --build

1. 从添加反向代理配置 deploy/nginx-mcp.conf 到你的nginx服务器块。
2. 验证并重新加载nginx：

   sudo nginx -t
   sudo systemctl reload nginx

1. 验证服务器：

   curl http://127.0.0.1:8080/health

重要提示： HTTP服务器不使用 NEXTCLOUD_* 环境变量。在自托管模式下，每个客户端都必须通过请求头提供Nextcloud凭据。在密钥服务模式下，客户端仅发送 api_key=usr_....

远程MCP注意事项： 对于Claude.ai等托管连接器，首选基于路径的URL形式(/mcp/usr_...).保留查询参数表单作为检查器和客户端的兼容性选项，以可靠地保留查询参数。

调试注意事项： 如果托管客户端显示通用身份验证提示，则并不自动意味着需要OAuth。首先验证免身份验证诊断路由、密钥服务解析器响应和实际 initialize SSE机构。

选项3:npm包（CLI）

安装并作为本地MCP服务器运行：

npm install -g mcp-nextcloud
mcp-nextcloud

注： 在CLI模式下，从环境变量读取凭据(NEXTCLOUD_HOST, NEXTCLOUD_USERNAME, NEXTCLOUD_PASSWORD).这是安全的，因为CLI模式在本地为单个用户运行。

方案4：史密瑟里部署

对于Smithery当前发布的URL模型，使用一个专用端点，通过标头接受直接Nextcloud凭据：

# Enable the Smithery endpoint on your hosted server
ENABLE_SMITHERY_ENDPOINT=true

在Smithery中使用此公共MCP URL：

https://mcp.techmavie.digital/nextcloud/smithery/mcp

此服务器的推荐Smithery配置架构：

{
  "type": "object",
  "properties": {
    "nextcloudHost": {
      "type": "string",
      "title": "Nextcloud Host",
      "description": "Nextcloud server URL (for example https://cloud.example.com)",
      "x-from": { "header": "X-Nextcloud-Host" }
    },
    "nextcloudUsername": {
      "type": "string",
      "title": "Nextcloud Username",
      "x-from": { "header": "X-Nextcloud-Username" }
    },
    "nextcloudPassword": {
      "type": "string",
      "title": "Nextcloud App Password",
      "format": "password",
      "x-from": { "header": "X-Nextcloud-Password" }
    }
  },
  "required": ["nextcloudHost", "nextcloudUsername", "nextcloudPassword"]
}

为什么推荐这种拆分：

• Smithery用户可以直接连接，而无需先创建MCP密钥服务密钥
• 主办 usr_... Claude.ai和其他托管客户端的连接器流保持不变
• Smithery小径与 /smithery/mcp，所以它不会干扰 /mcp 或 /mcp/usr_...

重要提示： Smithery端点是为通过标头进行直接凭据而设计的。它不使用MCP密钥服务，也不需要共享 MCP_API_KEY. 为了帮助Smithery在不强制进行实时身份验证扫描的情况下发现工具，此服务器还公开了一个静态服务器卡 https://mcp.techmavie.digital/.well-known/mcp/server-card.json。如果您的反向代理在以下位置挂载应用程序 /nextcloud，确保将确切的根级别已知路径代理到应用程序。

发布到npm

对于维护人员

要将此包发布到npm：

1. 准备发布：

   npm run build
   npm version patch|minor|major

1. 发布到npm：

   npm publish

1. 验证发布：

   npm view mcp-nextcloud

发布检查表

• \[\]所有测试均通过（Smithery部署确认有效）
• \[\]TypeScript构建时没有错误(npm run build)
• \[\]版本已适当升级(npm version)
• \[\]README已更新
• \[ \] .npmignore 正确排除开发文件
• \[\]CLI可执行文件工作(dist/cli.js)

双重部署策略

此项目同时支持两种部署方法：

• 史密瑟里：用于云部署和开发测试
• npm：用于最终用户安装和MCP客户端集成

Smithery配置(smithery.yaml)npm包配置共存，互不干扰。

Smithery集成

该项目包括Smithery的全面支持，包括：

• smithery.yaml：指定TypeScript运行时
• 开发服务器：热重新加载的本地测试
• 一键部署：只需一个命令即可部署到云端
• 配置管理：安全的凭证处理
• 游乐场集成：即时测试界面

安全

HTTP服务器安全模型

HTTP服务器(http-server.ts)支持两种身份验证模式：

关键服务模式 （托管/多用户）：

• 用户API密钥(usr_...)通过MCP密钥服务解析，该服务返回加密的Nextcloud凭据。
• 客户端不发送原始凭据，只发送用户指定的API密钥。
• 凭据缓存60秒以减少密钥服务负载，然后重新验证。

自托管模式 （单个操作员）：

• 服务器端 MCP_API_KEY 验证访问。
• 每个客户端通过以下方式提供Nextcloud凭据 X-Nextcloud-* 标题。

常见安全措施：

• 按请求凭据隔离：每个请求都会通过以下方式获得一组独立的Nextcloud客户端 AsyncLocalStorage。请求之间不共享凭据状态。
• 无环境变量回退：HTTP服务器永远不会回退到 NEXTCLOUD_* 凭据的环境变量。这些仅在CLI模式下使用。
• 受限CORS：仅列出来源 ALLOWED_ORIGINS 允许（默认为 smithery.ai 和 claude.ai).
• 受保护的分析：The /analytics 端点需要 MCP_API_KEY 两种模式下的身份验证。仪表板页面将密钥存储在会话存储中，从不存储在URL中。客户端IP在存储之前会被散列。
• 生产环境中禁用调试工具：日历调试工具在以下情况下会自动禁用 NODE_ENV=production.

自助主机清单

如果部署自己的实例：

1. 选择身份验证模式：set KEY_SERVICE_URL + KEY_SERVICE_TOKEN 用于密钥服务，或 MCP_API_KEY 对于自托管
2. 集 MCP_API_KEY 用于分析访问（两种模式都需要）
3. 不要设置 NEXTCLOUD_* HTTP服务器上的环境变量
4. 对所有连接使用HTTPS（TLS）
5. 配置 ALLOWED_ORIGINS 限制可以连接的域
6. 使用Nextcloud应用程序密码（不是您的主登录密码）

故障排除

常见问题

1. WebDAV/日历/联系人出现404错误:

- 确保您的Nextcloud凭据正确 - 验证Nextcloud应用程序（日历、联系人）是否已安装并启用 - 检查您的应用程序密码是否具有必要的权限

1. 身份验证失败:

- 使用应用程序密码而不是常规密码 - 验证 NEXTCLOUD_HOST URL正确（包括https://） - 确保Nextcloud实例可访问

1. 缺少工具:

- 跑 hello 用于验证所有30个工具是否可用的工具 - 检查服务器日志是否有任何初始化错误

1. 搜索超时问题:

- 使用 quickSearch: true 用于根目录搜索 - 指定一个 basePath 类似于“/Documents”而不是搜索根“/” - 添加 fileTypes 筛选以缩小搜索范围 - 减少 maxDepth 参数以获得更快的结果

托管HTTP/Claude.ai调试

如果托管连接器仍然失败，请使用以下顺序：

1. 首先验证免身份验证诊断路由：

- 启用 ENABLE_MCP_DIAGNOSTICS=true - 测试 /mcp-debug/open - 如果这有效，问题可能是身份验证或上游依赖，而不是基本的MCP传输

1. 直接从部署的MCP主机验证密钥服务解析器：

   curl -i -X POST "$KEY_SERVICE_URL" \
     -H "Authorization: Bearer $KEY_SERVICE_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"key":"usr_..."}'

预期： - 200 OK - Content-Type: application/json - 有效的JSON响应

1. 验证MCP初始化响应体，而不仅仅是状态代码：

   curl -N --max-time 10 -X POST "https://mcp.techmavie.digital/nextcloud/mcp/usr_XXXXXXXX" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"probe","version":"1.0.0"}}}'

预期： - 200 OK - Content-Type: text/event-stream - 非空SSE初始化响应体

1. 如果托管客户端每隔几秒钟重试一次相同的初始化请求，即使HTTP状态为 200.
2. 启用临时跟踪 MCP_TRACE_HTTP=true 并检查：

- 最终状态代码 - 请求 accept - 请求 content-type - content-type 响应头 - 身份验证结果(resolved, invalid_key, service_unavailable, malformed_response)

发展

项目结构

├── src/
│   ├── index.ts          # Main Smithery entry point
│   ├── http-server.ts    # Streamable HTTP server for VPS deployment
│   ├── app.ts            # Legacy entry point
│   ├── client/           # Nextcloud API clients
│   ├── models/           # TypeScript interfaces
│   ├── tools/            # Tool implementations
│   └── utils/            # Utility functions
├── deploy/
│   └── nginx-mcp.conf    # Nginx reverse proxy config
├── .github/
│   └── workflows/
│       └── deploy-vps.yml # GitHub Actions auto-deploy
├── docker-compose.yml    # Docker deployment config
├── Dockerfile            # Container build config
├── smithery.yaml         # Smithery configuration
├── package.json          # Project dependencies and scripts
└── README.md             # This file

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 测试用 npm run dev
5. 提交拉取请求

许可证

此项目根据GNU Affero通用公共许可证v3.0（AGPL-3.0）获得许可-请参阅 许可证 文件以获取详细信息。

致谢

• 原始Python实现 cb库蒂尼奥
• 建于 模型上下文协议
• 可通过以下方式部署 史密瑟里