# mongo_mcp_server

**Repository Path**: boliu15/mongo_mcp_server

## Basic Information

- **Project Name**: mongo_mcp_server
- **Description**: MongoDB MCP Server 是一个基于 Model Context Protocol (MCP) 的 MongoDB 数据库操作服务器，可以让 Claude Desktop 等 MCP 客户端直接操作 MongoDB 数据库。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-19
- **Last Updated**: 2025-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MongoDB MCP Server

MongoDB MCP Server 是一个基于 Model Context Protocol (MCP) 的 MongoDB 数据库操作服务器，可以让 Claude Desktop 等 MCP 客户端直接操作 MongoDB 数据库。

## 🚀 快速开始

### 从 Gitee 安装

#### 1. 克隆仓库

```bash
git clone https://gitee.com/your-username/mcp-mongodb-server.git
cd mcp-mongodb-server
```

#### 2. 安装依赖并构建

```bash
npm install
npm run build
```

#### 3.打包

```bash
npm pack
```

#### 4. 全局安装

```bash
npm install -g ./mongo-mcp-server-1.0.0.tgz
```



安装完成后，`mcp-mongodb-server` 命令将在全局可用。

#### 5. 验证安装

```bash
# 检查是否安装成功
npm list -g mcp-mongodb-server

```

## ⚙️ 配置 Claude Desktop

### Windows 配置

编辑配置文件：`%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mongodb": {
      "command": "mongo-mcp-server",
      "env": {
        "MONGODB_URI": "mongodb://admin:<password>@<ip>:<port>/<databaseName>?authSource=admin"
      }
    }
  }
}
```



### MongoDB 连接配置

根据你的 MongoDB 部署方式，使用不同的连接字符串：

```bash
# 本地 MongoDB
MONGODB_URI="mongodb://admin:<password>@<ip>:<port>/<databaseName>?authSource=admin"

```

### 重启 Claude Desktop

配置完成后，完全退出并重新启动 Claude Desktop，MCP 服务器将自动连接。

## 🎯 使用示例

配置完成后，在 Claude Desktop 中可以这样使用：

### 列出所有数据库

```
请列出 MongoDB 中的所有数据库
```

### 查询数据

```
请查询 mydb 数据库中 users 集合里年龄大于 18 的所有用户
```

### 插入数据

```
请在 mydb 数据库的 users 集合中插入一个新用户：
名字是 John，年龄 25，邮箱是 john@example.com
```

### 更新数据

```
请将 mydb 数据库 users 集合中名字为 John 的用户年龄更新为 26
```

### 删除数据

```
请删除 mydb 数据库 users 集合中年龄小于 18 的所有用户
```

### 聚合查询

```
请统计 mydb 数据库 orders 集合中每个用户的订单总金额
```

## 📚 可用工具

### 1. mongodb_query
查询 MongoDB 集合中的文档

**参数：**
- `database`: 数据库名称
- `collection`: 集合名称
- `query`: 查询条件（JSON字符串）
- `options`: 查询选项（可选，JSON字符串）

### 2. mongodb_insert
向 MongoDB 集合插入文档

**参数：**
- `database`: 数据库名称
- `collection`: 集合名称
- `document`: 要插入的文档（JSON字符串）

### 3. mongodb_update
更新 MongoDB 集合中的文档

**参数：**
- `database`: 数据库名称
- `collection`: 集合名称
- `filter`: 筛选条件（JSON字符串）
- `update`: 更新操作（JSON字符串）

### 4. mongodb_delete
删除 MongoDB 集合中的文档

**参数：**
- `database`: 数据库名称
- `collection`: 集合名称
- `filter`: 筛选条件（JSON字符串）

### 5. mongodb_aggregate
在 MongoDB 集合上执行聚合管道操作

**参数：**
- `database`: 数据库名称
- `collection`: 集合名称
- `pipeline`: 聚合管道（JSON数组字符串）

### 6. mongodb_list_databases
列出所有数据库

### 7. mongodb_list_collections
列出指定数据库中的所有集合

**参数：**
- `database`: 数据库名称

## 🔧 开发模式

如果你想修改代码并实时测试：

```bash
# 1. 克隆仓库
git clone https://gitee.com/your-username/mcp-mongodb-server.git
cd mcp-mongodb-server

# 2. 安装依赖
npm install

# 3. 使用 npm link 创建全局链接
npm link

# 4. 修改代码后重新构建
npm run build

# 5. 测试（修改会立即生效）
```

取消链接：

```bash
npm unlink -g mcp-mongodb-server
```

## 🔄 更新

当仓库有更新时：

```bash
# 进入项目目录
cd mcp-mongodb-server

# 拉取最新代码
git pull

# 重新构建
npm run build

# 如果使用 npm install -g，需要重新安装
npm install -g .

# 如果使用 npm link，构建后即可生效
```

## 🗑️ 卸载

```bash
# 全局卸载
npm uninstall -g mcp-mongodb-server

# 或者取消链接
npm unlink -g mcp-mongodb-server
```

## 🐛 故障排查

### 问题 1: 找不到 mcp-mongodb-server 命令

**解决方案：**
```bash
# 检查全局安装
npm list -g mcp-mongodb-server

# 重新安装
cd mcp-mongodb-server
npm install -g .
```

### 问题 2: Claude Desktop 无法连接

**解决方案：**
- 确保已运行 `npm run build`
- 检查配置文件路径是否正确
- 重启 Claude Desktop
- 查看 Claude Desktop 的开发者工具控制台

### 问题 3: MongoDB 连接失败

**解决方案：**
- 检查 MongoDB 服务是否运行
- 验证 `MONGODB_URI` 连接字符串是否正确
- 检查网络连接和防火墙设置
- 确认 MongoDB 用户权限

### 问题 4: 权限错误

**解决方案：**
```bash
# Linux/macOS 可能需要 sudo
sudo npm install -g .

# 或者配置 npm 全局目录
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
```

## 📁 项目结构

```
mcp-mongodb-server/
├── src/
│   ├── server.ts          # MCP服务器主文件
│   ├── mongodb-client.ts  # MongoDB连接和操作封装
│   └── tools/             # MCP工具定义
│       └── mongodb-tools.ts
├── dist/                  # 编译后的文件（构建生成）
├── tsconfig.json         # TypeScript配置
├── package.json          # 项目配置
└── README.md             # 项目说明
```

## 🔐 安全建议

1. **不要在配置文件中硬编码密码**
   - 使用环境变量
   - 使用 MongoDB 的认证机制

2. **使用安全的连接字符串**
   - 生产环境使用 TLS/SSL
   - 使用强密码
   - 限制数据库用户权限

3. **定期更新依赖**
   ```bash
   npm update
   npm audit fix
   ```

## 📄 许可证

MIT

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 支持

- Gitee Issues: https://gitee.com/your-username/mcp-mongodb-server/issues
- 文档: 查看本 README 和 CONFIGURATION.md

## 🌟 相关链接

- [MCP 官方文档](https://modelcontextprotocol.io/)
- [MongoDB Node.js 驱动文档](https://www.mongodb.com/docs/drivers/node/)
- [Claude Desktop](https://claude.ai/desktop)