Mango MCP Main 2

MongoDB MCP与Agno OpenAI代理的集成

该项目演示了如何将MongoDB模型上下文协议（MCP）服务器与Agno OpenAI代理集成，实现与MongoDB数据库的自然语言交互。

概述

集成允许您：

• 使用自然语言查询MongoDB数据库
• 分析集合模式和数据结构
• 执行聚合和数据分析
• 列出数据库、集合和索引
• 可选地执行写入操作（插入、更新、删除）

先决条件

• Python 3.8+
• Node.js （用于通过以下方式运行MongoDB MCP服务器 npx)
• MongoDB （本地实例或MongoDB Atlas集群）
• OpenAI API密钥

安装

1. 克隆或下载此项目

1. 安装Python依赖项：

   pip install -r requirements.txt

1. 设置环境变量：

复制 .env.example 到 .env 并填写您的凭据：

   cp .env.example .env

编辑 .env 根据您的实际值：

- MDB_MCP_CONNECTION_STRING：您的MongoDB连接字符串 - OPENAI_API_KEY：您的OpenAI API密钥

配置选项

选项1:MongoDB连接字符串

使用直接连接字符串连接到任何MongoDB实例（本地或Atlas）：

MDB_MCP_CONNECTION_STRING=mongodb://localhost:27017/myDatabase

对于MongoDB Atlas：

选项2：Atlas API证书

使用Atlas服务帐户凭据进行高级Atlas管理：

MDB_MCP_API_CLIENT_ID=your-client-id
MDB_MCP_API_CLIENT_SECRET=your-client-secret

用法

基础示例

运行默认示例：

python app.py

自定义查询

修改 __main__ 部分在 app.py 要运行自定义查询，请执行以下操作：

# Query databases
asyncio.run(run_mongodb_agent("List all databases and their collections"))

# Analyze schema
asyncio.run(run_mongodb_agent("Show me the schema of the 'users' collection"))

# Query data
asyncio.run(run_mongodb_agent("Find the top 5 users by age"))

可用功能

1. run_mongodb_agent(message)

使用连接字符串进行只读访问的基本MongoDB代理。

asyncio.run(run_mongodb_agent("List all collections in myDatabase"))

2. run_mongodb_agent_with_atlas_api(message)

使用Atlas API凭据进行集群管理的MongoDB代理。

asyncio.run(run_mongodb_agent_with_atlas_api("List all my Atlas clusters"))

3. run_mongodb_agent_with_context_manager(message)

使用异步上下文管理器进行自动连接管理。

asyncio.run(run_mongodb_agent_with_context_manager("How many documents are in each collection?"))

4. run_mongodb_agent_with_write_access(message)

⚠️ 小心使用！ 启用写入操作（插入、更新、删除）。

asyncio.run(run_mongodb_agent_with_write_access("Insert a test document"))

关键集成模式

集成遵循以下模式：

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.mcp import MCPTools

# 1. Initialize MongoDB MCP Tools
mcp_tools = MCPTools(
    command="npx -y mongodb-mcp-server@latest --readOnly",
    env={"MDB_MCP_CONNECTION_STRING": connection_string}
)

# 2. Connect to MCP server
await mcp_tools.connect()

try:
    # 3. Create Agno Agent with OpenAI model
    agent = Agent(
        name="MongoDB Assistant",
        model=OpenAIChat(id="gpt-4o-mini"),
        tools=[mcp_tools],
        instructions="You are a MongoDB database assistant...",
        markdown=True,
    )
    
    # 4. Run the agent
    await agent.aprint_response(message, stream=True)
    
finally:
    # 5. Always close the connection
    await mcp_tools.close()

安全最佳实践

1. 默认情况下为只读：The --readOnly 默认情况下，为了安全起见，会包含该标志
2. 环境变量：将敏感凭据存储在 .env file（永远不要提交到git）
3. 最低权限：使用Atlas API时，只分配所需的权限
4. 写入确认：启用写入的代理在执行破坏性操作之前会要求确认

MongoDB MCP服务器选项

常见配置选项：

• --readOnly：启用只读模式（为安全起见建议）
• --maxDocumentsPerQuery 100：限制每次查询返回的文档
• --maxBytesPerQuery 16777216：限制每个查询的字节数
• --loggers disk,mcp：配置日志记录目标

看 MongoDB MCP服务器文档 对于所有选项。

故障排除

连接问题

1. 验证MongoDB是否正在运行：

   # For local MongoDB
   mongosh mongodb://localhost:27017

1. 检查连接字符串格式：

- 当地： mongodb://localhost:27017/database

Node.js/npx问题

确保已安装Node.js：

node --version
npx --version

OpenAI API问题

验证您的API密钥是否已设置：

echo $env:OPENAI_API_KEY

资源

• Agno文件
• Agno MCP概述
• MongoDB MCP服务器
• 模型上下文协议
• MongoDB文档

示例

示例1：列出数据库

asyncio.run(run_mongodb_agent("List all databases"))

示例2：模式分析

asyncio.run(run_mongodb_agent("Analyze the schema of the users collection"))

示例3：数据聚合

asyncio.run(run_mongodb_agent("Show me the average age by country in the users collection"))

示例4：索引信息

asyncio.run(run_mongodb_agent("List all indexes on the products collection"))

许可证

MIT许可证-可根据需要自由使用和修改。