# TeiNam
## 基本信息
- Slug: `teinam-mongo-mcp-server`
- Source: modelscope
- Publisher: @TeiNam/mongo-mcp-server
- Categories: databases / data-platforms / rag-systems
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@TeiNam/mongo-mcp-server
## 简介
暂无描述。
## MCP Server 详情

# MongoDB MCP 服务器

![Python](https://img.shields.io/badge/Python-3.12-blue.svg)
![FastAPI](https://img.shields.io/badge/FastAPI-0.115.12-green.svg)
![FastMCP](https://img.shields.io/badge/FastMCP-2.3.3-yellow.svg)
![MongoDB](https://img.shields.io/badge/MongoDB-4.4-orange.svg)
![Anthropic](https://img.shields.io/badge/Claude-3.7--Sonnet-purple.svg)
![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)

这是一个强大的 Model Context Protocol (MCP) 服务器实现，通过标准化协议提供与 MongoDB 数据库的顺畅交互。

## 作者

**Rastalion**

## 概述

此 MCP 服务器实现提供了通过 Model Context Protocol 与 MongoDB 数据库进行交互的强大接口。它通过 async/await 模式和错误处理稳定地支持对数据库、集合及文档的操作。

## 特性

* 完全支持 MongoDB CRUD 操作
* 安全处理与 MongoDB 的连接
* 为最佳性能采用异步 (async/await) 模式
* 全面的错误处理
* 支持 Docker 以方便部署
* 带有类型提示的查询执行
* 支持 SSE（Server-Sent Events）用于实时更新

## 快速开始

### 作为 CLI 工具使用

bash
# 克隆仓库
git clone https://github.com/yourusername/mongo-mcp-server.git
cd mongo-mcp-server

# 开发模式安装
pip install -e .

# 本地运行 CLI 命令
mongo-mcp-server

# 使用 SSE 传输方式运行
mongo-mcp-server --transport=sse

# 指定 MongoDB URL
mongo-mcp-server --mongodb-url="mongodb://username:password@hostname:port/dbname"

# 查看帮助
mongo-mcp-server --help


### 通过 UVX 运行

bash
# 如果已安装 UVX
uvx mongo-mcp-server

# SSE 传输模式
uvx mongo-mcp-server --transport=sse


### 直接用 Python 运行

bash
# 克隆仓库
git clone https://github.com/yourusername/mongo-mcp-server.git
cd mongo-mcp-server

# 安装依赖
pip install -r requirements.txt

# 设置环境变量
export MONGODB_URL="mongodb://username:password@hostname:port/dbname?authSource=admin"

# 启动服务器
uvicorn app.main:app --host 0.0.0.0 --port 3000


### 使用 Docker

bash
# 克隆仓库
git clone https://github.com/yourusername/mongo-mcp-server.git
cd mongo-mcp-server

# 使用 Docker Compose 构建并运行
docker-compose up -d

# 查看日志
docker-compose logs -f mongo-mcp


### 使用 UVX

UVX 是一个可以在多种环境中轻松管理服务的工具。

bash
# 给注册脚本添加执行权限
chmod +x uvx-register.sh

# 在 UVX 中注册服务
./uvx-register.sh

# 启动服务
uvx start mongo-mcp

# 检查状态
uvx status mongo-mcp

# 查看日志
uvx logs mongo-mcp


更多详细信息，请参阅 [UVX 指南](./UVX_GUIDE.md)。

## 环境变量

在启动服务器之前，请设置以下环境变量：

bash
# 必需
MONGODB_URL="mongodb://username:password@hostname:port/dbname?authSource=admin"

# 可选 - 显示默认值
PORT=3000
MCP_TRANSPORT=http  # http 或 sse


## API 端点

- **健康检查**: `GET /health`
- **MCP API**: `GET /mcp` - FastMCP 端点 (OpenAPI 文档)
- **SSE 连接**: `GET /sse` - Server-Sent Events 端点
- **消息处理**: `POST /messages` - 消息处理端点

## IDE 集成

### VS Code 设置

在 VS Code 的 settings.json 文件中添加以下内容：

json
{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "mongodbUri",
        "description": "MongoDB 连接 URI"
      }
    ],
    "servers": {
      "mongodb": {
        "command": "mongo-mcp-server",
        "args": [
          "--mongodb-url",
          "$(mongodbUri)"
        ],
        "env": {}
      }
    }
  }
}### Claude 或其他 AI 助手

为 Claude 或其他 AI 助手配置 MCP 服务器如下：

json
{
  "mcp": {
    "servers": {
      "mongodb": {
        "url": "http://localhost:3000/mcp"
      }
    }
  }
}


## 可用工具

| 工具名称             | 描述                             |
|-------------------|--------------------------------|
| `listCollections` | 查询数据库中所有可用的集合列表    |
| `find`            | 使用 MongoDB 查询语法查询集合中的文档 |
| `insertOne`       | 向集合插入单个文档                  |
| `updateOne`       | 更新集合中的单个文档               |
| `deleteOne`       | 删除集合中的单个文档                 |
| `indexes`         | 查询集合的所有索引列表              |
| `createIndex`     | 为集合创建新索引                |
| `dropIndex`       | 删除集合中的现有索引                |

## 高级用法

### 添加自定义工具

1. 在 `app/tools/documents/` 或 `app/tools/collection/` 中创建新工具：

python
from ..base.tool import BaseTool


class MyNewTool(BaseTool):
    @property
    def name(self) -> str:
        return "my_new_tool"

    @property
    def description(self) -> str:
        return "新工具的描述"

    @property
    def input_schema(self) -> Dict[str, Any]:
        return {
            "type": "object",
            "properties": {
                # 定义工具输入模式
            }
        }

    async def execute(self, params: Dict[str, Any]) -> Dict[str, Any]:
        # 实现工具执行逻辑
        pass


2. 在 `app/tools/registry.py` 中注册工具：

python
from .documents.my_new_tool import MyNewTool

# 在 ToolRegistry.__init__ 方法内
self.register_tool(MyNewTool())


### CLI 工具安装与部署

可以通过将包注册到 PyPI 来全局使用：

bash
# 检查 setup.py 并构建
python setup.py sdist bdist_wheel

# 上传包（需要 PyPI 账户）
twine upload dist/*

# 全局安装
pip install mongodb-mcp-bridge

# 从任何地方运行
mongodb-mcp-bridge


## 故障排除

- **服务器无法启动**：使用 `mongo-mcp-server --help` 查看帮助
- **MongoDB 连接问题**：检查 `--mongodb-url` 参数是否正确
- **工具执行错误**：检查工具实现和输入参数
- **Docker 问题**：使用 `docker-compose logs mongo-mcp` 查看日志

## Docker 配置

Docker 设置包括以下内容：

- Python 3.12 基础镜像
- Asia/Seoul 时区
- MongoDB 4.4 实例
- 用于数据库存储的持久化卷
- 对两个服务的健康检查
- 自动化的网络配置

## 许可证

本项目根据 MIT 许可证分发 - 详情请参阅 [LICENSE](LICENSE) 文件。