使用说明

ro mongodb mcp rs

高性能模型上下文协议（MCP）执行服务器 只读MongoDB查询内置Rust，速度快，可靠性高。

概述

该服务器使LLM能够通过MCP协议安全地查询MongoDB数据库。它支持两种连接类型：

连接类型	用例	速度
直接URL	本地、Atlas、任何网络可访问的MongoDB	~13ms
Kubernetes	MongoDB在K8s Pod中运行	~700ms

特性

只读查询 -只有 find, aggregate, countDocuments，以及 distinct 运营
查询控件 -查找操作的限制、排序和投影参数
双连接支持 -Kubernetes Pod和直接MongoDB URL
保存的带有变量的查询 -使用保存可重用查询 {{placeholder}} 变量
模式集成 -数据模型文件帮助LLM了解您的集合
自动发现 -从pod环境中自动发现K8s凭据
超时保护 -30秒查询超时可防止查询失控
快速启动 -~4ms冷启动，缓存操作为亚毫秒级

快速开始

1.建造

cargo build --release

2.配置

创建 ~/.config/ro-mongodb-mcp-rs/config.yaml:

# Direct connection (simplest)
connections:
  - name: local
    mongodb_url: mongodb://localhost:27017
    database_name: mydb
    # data_model_file_path: /path/to/schema.md  # optional

或者复制并自定义示例：

cp config.example.yaml ~/.config/ro-mongodb-mcp-rs/config.yaml

3.跑步

./target/release/ro-mongodb-mcp-rs

服务器通过JSON-RPC 2.0在stdin/stdout上进行通信。

配置

配置文件： ~/.config/ro-mongodb-mcp-rs/config.yaml

直接MongoDB连接

对于本地开发、MongoDB Atlas或任何可通过网络访问的MongoDB：

connections:
  - name: local-dev
    mongodb_url: mongodb://localhost:27017
    database_name: myapp
    data_model_file_path: /path/to/schema.md

  - name: atlas-prod
    mongodb_url: mongodb+srv://user:pass@cluster.mongodb.net
    database_name: production
    data_model_file_path: /path/to/schema.md

Kubernetes命名空间连接

对于在Kubernetes集群中运行的MongoDB：

# Optional: custom kubeconfig
# kubeconfig_path: /path/to/kubeconfig

namespaces:
  - namespace_name: production      # K8s namespace (also the connection name)
    deployment_name: mongodb        # Pod label: app=mongodb
    database_name: myapp
    data_model_file_path: /path/to/schema.md

K8s凭据发现： 服务器从pod环境变量中读取凭据：

MONGO_INITDB_ROOT_USERNAME_FILE → 包含用户名的文件路径
MONGO_INITDB_ROOT_PASSWORD_FILE → 包含密码的文件路径

配置字段

字段	描述
`kubeconfig_path`	（可选）自定义kubeconfig文件路径（仅限K8s）
`name` / `namespace_name`	唯一连接标识符
`mongodb_url`	MongoDB连接字符串（仅限直接连接）
`deployment_name`	Pod标签选择器 `app=<value>` （仅限K8s）
`database_name`	查询的默认数据库
`data_model_file_path`	（可选）模式文档文件（任何格式）

路径扩展： 所有路径字段都支持环境变量($HOME, ${VAR})和瓷砖(~)扩张。

重要提示： 连接名称在所有连接中必须是唯一的。

MCP工具

服务器提供10个工具：

发现工具

工具	说明
`list_connections`	列出所有已配置的连接
`list_collections`	列出MongoDB集合（区分大小写的名称）
`get_data_model`	获取连接的架构文档
`get_current_time`	获取基于时间的查询的当前时间戳

查询工具

工具	说明
`query_mongodb`	执行只读MongoDB查询

支持的操作：

// find - retrieve documents
{"status": "active"}

// aggregate - pipeline queries
[{"$match": {}}, {"$group": {"_id": "$status", "count": {"$sum": 1}}}]

// countDocuments - count matching documents
{"status": "active"}

// distinct - unique values (use distinct_field param)
{}  // with distinct_field: "country"

可选参数（仅限查找）：

参数	说明	示例
`limit`	最多可退回的文件数	`10`
`sort`	排序顺序（JSON）	`{"createdAt": -1}`
`projection`	要包含/排除的字段	`{"name": 1, "email": 1}`
`distinct_field`	不同值字段	`"country"`

已保存的查询工具

工具	说明
`save_query`	保存查询以供以后重用
`list_saved_queries`	列出连接的所有已保存查询
`get_saved_query`	获取已保存查询的详细信息
`run_saved_query`	执行已保存的查询
`delete_saved_query`	删除已保存的查询

占位符变量： 保存查询支持 {{placeholder}} 运行时替换语法：

// Save with placeholders - quotes in template control output type
{
  "query": "{\"name\": \"{{name}}\", \"age\": {{age}}}"
}
//         "{{name}}" → string     {{age}} → number

// Run with variables (all values are strings)
{
  "variables": {"name": "John", "age": "25"}
}
// Result: {"name": "John", "age": 25}

运行时间覆盖： 仅对于查找操作，您可以覆盖 limit, sort，以及 projection。对于其他操作，这些将被忽略（并带有警告）。

储存： 查询在每个连接中持久化 ~/.local/share/ro-mongodb-mcp-rs/<connection>.queries.yaml

使用示例

基本查询

{
  "name": "query_mongodb",
  "arguments": {
    "connection_name": "local",
    "collection_name": "users",
    "operation": "find",
    "query": "{\"status\": \"active\"}",
    "limit": 10,
    "sort": "{\"createdAt\": -1}",
    "projection": "{\"name\": 1, \"email\": 1}"
  }
}

聚合管道

{
  "name": "query_mongodb",
  "arguments": {
    "connection_name": "local",
    "collection_name": "orders",
    "operation": "aggregate",
    "query": "[{\"$match\": {\"status\": \"completed\"}}, {\"$group\": {\"_id\": \"$userId\", \"total\": {\"$sum\": \"$amount\"}}}]"
  }
}

清点文件

{
  "name": "query_mongodb",
  "arguments": {
    "connection_name": "local",
    "collection_name": "users",
    "operation": "countDocuments",
    "query": "{}"
  }
}

不同的值

{
  "name": "query_mongodb",
  "arguments": {
    "connection_name": "local",
    "collection_name": "users",
    "operation": "distinct",
    "query": "{}",
    "distinct_field": "country"
  }
}

保存查询（带变量）

{
  "name": "save_query",
  "arguments": {
    "connection_name": "local",
    "query_name": "user_activity",
    "description": "Get user activity after a date",
    "collection_name": "events",
    "operation": "find",
    "query": "{\"userId\": \"{{userId}}\", \"createdAt\": {\"$gte\": \"{{startDate}}\"}}"
  }
}

运行已保存的查询（带变量）

{
  "name": "run_saved_query",
  "arguments": {
    "connection_name": "local",
    "query_name": "user_activity",
    "variables": {"userId": "12345", "startDate": "2024-01-01T00:00:00Z"},
    "limit": 100
  }
}

演出

典型硬件的基准测试：

度量	时间
二进制启动	4ms
`get_current_time`	<1ms
`list_connections`	<1ms
直接MongoDB查询	~13ms
K8s MongoDB查询	~700ms
10个连续直接查询	5ms（连接重用）

二进制大小：~21MB（发布版本）

MCP客户端集成

克劳德桌面版

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "mongodb": {
      "command": "/path/to/ro-mongodb-mcp-rs"
    }
  }
}

Goose命令行界面

添加到 ~/.config/goose/config.yaml:

extensions:
  mongodb:
    bundled: false
    display_name: "MongoDB"
    enabled: true
    name: "mongodb"
    timeout: 300
    type: "stdio"
    cmd: "/path/to/ro-mongodb-mcp-rs"
    args: []

或者通过交互方式添加 goose configure 并选择“命令行扩展”。

通用MCP客户端

服务器通过stdin/stdout使用JSON-RPC 2.0：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | ./ro-mongodb-mcp-rs

发展

先决条件

Rust 1.85或更高版本（2024年版）
对于K8s连接：具有集群访问权限的有效kubeconfig
对于直接连接：MongoDB的网络访问

构建

cargo build --release

测试

cargo test

调试日志记录

RUST_LOG=ro_mongodb_mcp_rs=debug ./target/release/ro-mongodb-mcp-rs

棉绒

cargo clippy --all-targets

版本管理

检查版本：

./ro-mongodb-mcp-rs --version

发布新版本：

./set-version.sh 1.2.3
git push origin main --follow-tags

故障排除

“未找到健康的Pod”（Kubernetes）

# Check pods exist and are running
kubectl get pods -n <namespace> -l app=<deployment_name>

# Verify pod is healthy
kubectl describe pod <pod-name> -n <namespace>

“找不到MongoDB凭据环境变量”（Kubernetes）

# Check pod environment variables
kubectl exec -n <namespace> <pod-name> -- env | grep MONGO

所需变量：

MONGO_INITDB_ROOT_USERNAME_FILE
MONGO_INITDB_ROOT_PASSWORD_FILE

“读取数据模型文件失败”

验证文件是否存在： ls -la /path/to/schema.md
路径支持 $HOME, ${VAR}，以及 ~ 扩张

连接超时（直接）

验证MongoDB是否正在运行： mongosh mongodb://localhost:27017
检查网络连接
验证URL中的凭据是否正确

查询超时

查询在30秒后超时。对于大型数据集：

添加过滤器以减小结果大小
使用 $limit 聚合管道中
使用 countDocuments 首先检查数据大小

项目结构

src/
├── main.rs              # Entry point, CLI, initialization
├── config.rs            # Configuration loading and validation
├── connection.rs        # MongoConnection trait and registry
├── direct_connection.rs # Direct MongoDB URL connections
├── k8s_connection.rs    # Kubernetes namespace connections
├── k8s_client.rs        # Kubernetes API interactions
├── mcp.rs               # MCP server and tool implementations
├── mongodb.rs           # Query operations and mongosh execution
├── saved_queries.rs     # Query persistence
└── tools.rs             # MCP tool parameter types

安全

按设计只读 -仅支持读取操作
无查询注入 -操作在执行前经过验证
凭证隔离 -K8s凭据保留在群集中
超时保护 -30秒限制可防止资源耗尽

注：直接连接URL可能包含凭据。确保您的配置文件安全：

chmod 600 ~/.config/ro-mongodb-mcp-rs/config.yaml

许可证

MIT许可证。看许可证了解详情。