ravendb-mcp

RavenDB MCP

用于 RavenDB 的本地只读 MCP 诊断服务。将其连接到集群后，AI Agent 即可检查集群、数据库、索引、任务、存储和性能状态，以及日志、支持包和数据，共提供 21 个只读工具。

快速开始

使用 npx（Node.js）、dnx（.NET SDK）或从 Releases 下载预构建二进制文件来启动，然后将其添加到客户端。将 RAVENDB_URLS 设置为你的集群地址；示例使用 http://localhost:8080。

Claude Code

claude mcp add ravendb --scope user --env RAVENDB_URLS=http://localhost:8080 -- npx -y @ravendb/mcp

也可以安装插件，安装时会提示输入集群 URL：

/plugin marketplace add ravendb/ravendb-mcp
/plugin install ravendb-mcp@ravendb

Claude Desktop

从 Releases 下载 ravendb-mcp-<version>.mcpb，然后在 Settings > Extensions > Advanced settings > "Install Extension…" 下安装（参阅 Anthropic 指南）。安装时会提示输入集群 URL，因此无需编辑配置，也无需安装 Node 或 .NET。配置文件设置请参阅 INSTALL.md。

Codex

添加到 ~/.codex/config.toml：

[mcp_servers.ravendb]
command = "npx"
args = ["-y", "@ravendb/mcp"]
env = { RAVENDB_URLS = "http://localhost:8080" }

Cursor

点击按钮（使用 http://localhost:8080 安装；如需连接其他集群，请进行编辑），或添加 .cursor/mcp.json：

{
  "mcpServers": {
    "ravendb": {
      "command": "npx",
      "args": ["-y", "@ravendb/mcp"],
      "env": { "RAVENDB_URLS": "http://localhost:8080" }
    }
  }
}

然后让 Agent “列出我的 RavenDB 数据库。” 以上任一方式都可以用 dnx RavenDB.Mcp --yes 或二进制文件路径替代 npx -y @ravendb/mcp。有关安全（HTTPS）集群、其他操作系统和完整配置参考，请参阅 INSTALL.md。

功能

开发体验

• 使用 npx、dnx 或预构建二进制文件，一行命令即可安装。
• 提供 21 个工具，每个工具对应一个主题领域，并可通过参数选择所需内容（从 74 个精简而来）。
• 版本感知的 RQL 文档以 rql:// 资源形式提供；查询失败时会返回解析器错误及排查位置。

安全性

• 只读：不提供写入、修补或删除工具，并且会拒绝变更数据的查询。
• 返回的 JSON 会对连接字符串机密（密码、云密钥、SAS 令牌、AI 提供商密钥、证书）进行遮蔽。
• 访问权限受客户端证书的 RavenDB 权限限制。
• get_document_data 和 run_query 会将真实集群数据返回到 Agent 的上下文中——由你选择要公开哪个集群。请参阅 SECURITY.md。

节省上下文窗口

• 渐进式信息呈现：工具默认返回概览，并可按需深入查看详情。
• 结果采用分页：run_query 接受 start 和 pageSize（最多 128 行），列表工具接受 pageSize。
• 日志导出和调试包会写入磁盘上的文件；工具返回文件路径和字节大小，而非文件内容。
• 除非你主动请求，否则查询结果不会包含逐文档元数据。

随处运行

• 通过 npm、NuGet、GitHub Releases 和 MCP Registry 分发。
• 提供适用于 Windows、macOS 和 Linux（x64 和 arm64）的独立二进制文件，无需安装运行时。
• 多集群部署时，每个集群运行一个独立实例。

配置

一个服务实例面向一个集群。唯一必需的设置是 URL；可通过环境变量或 --config JSON 文件传入该 URL（以及可选的证书／制品设置）：

变量	必需	用途
RAVENDB_URLS	是	集群节点 URL，以逗号分隔；客户端会在这些节点之间进行故障转移。
RAVENDB_CERTIFICATE_PATH / _PASSWORD	否	用于安全（HTTPS）集群的客户端 .pfx。非安全集群无需设置。
RAVENDB_ARTIFACTS_PATH	否	导出文件的写入位置（默认为临时文件夹）。

完整配置参考（包括安全集群和多集群设置）请见 INSTALL.md。

工具

21 个只读工具（snake_case）。大多数是分面工具：每个主题对应一个工具，接受选择器，并且只返回你请求的部分。

• 分面： get_cluster_overview、get_server_config、get_server_resources、get_network_details、get_database_stats、get_database_config、get_index、get_tasks、get_live_workload、inspect_storage、get_document_data、sample_live_feed、wait_for_completion、collect_debug_package、get_ai_agents
• 单例： list_databases、get_database_record、get_notifications、run_query、list_compare_exchange、export_server_logs

较大或二进制输出（日志、调试包）会写入文件，并以引用形式返回。

隐私

RavenDB MCP 在本地运行，不会向 RavenDB 或 Anthropic 发送任何数据：没有遥测，也没有分析数据。它只连接到你配置的集群 URL（以及通过 npx／dnx 安装时连接到 npm/NuGet），将结果返回给你的本地 Agent，遮蔽连接字符串中的机密信息，并且只将导出内容写入你控制的本地文件夹。详情请见 PRIVACY.md；RavenDB 的公司政策见 ravendb.net。

许可证

MIT。请见 LICENSE。从源代码构建的说明请见 INSTALL.md。

---

mcp-name: io.github.ravendb/ravendb-mcp