MinIO-MCP服务器

Name: MinIO-MCP服务器
Author: Rafitis

作者：Rafitis4 星标更新：2025-10-13

安装使用来源：spider==github.com

项目介绍

MinIO MCP 服务器

这是一个模型上下文协议（MCP）服务器，作为MCP兼容客户端与MinIO对象存储之间的桥梁。该服务器将MinIO操作暴露为MCP工具，以实现无缝的桶管理和对象操作。

特性

7个MCP工具按领域组织，用于全面的MinIO操作：

桶管理

list_buckets: 列出所有可用的桶及其创建日期
get_bucket_info: 获取详细的桶信息（元数据、策略、对象数量、总大小、加密）
create_bucket: 创建新的桶，并进行名称验证和存在检查
delete_bucket: 删除空桶或强制删除包含所有内容的桶

对象管理

list_objects: 列出对象，支持过滤（前缀、递归）和可配置的限制（默认25）
get_object_info: 获取详细的对象元数据（大小、内容类型、etag、版本信息、自定义元数据）
delete_object: 从桶中删除对象，支持版本控制

主要特性

FastMCP集成：基于FastMCP框架，提供强大的MCP协议支持
全面验证：输入验证，错误处理并返回适当的HTTP状态码（400, 404, 409, 500）
异步架构：完全支持async/await，符合MCP协议
模块化设计：通过BucketTools和ObjectTools类分离关注点
广泛测试：100%测试覆盖率，采用高级模拟技术
标准化响应：通过TextContent实体进行一致的错误处理

快速开始

先决条件

Python 3.11 或更高版本
MinIO服务器（本地或远程）
UV包管理器（推荐）

安装

# 克隆仓库
git clone <repository-url>
cd minio-mcp-server

# 安装依赖
uv sync

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

配置

复制示例环境文件：

cp .env.example .env

在.env中配置你的MinIO连接：

MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_SECURE=false
MINIO_LOG_LEVEL=INFO

运行服务器

# 启动MCP服务器（stdio传输用于Claude Desktop）
uv run python src/minio_mcp/server.py

# 使用MCP Inspector测试（交互式测试）
uv run mcp src/minio_mcp/server.py

# 替代方案：直接执行Python
cd src/minio_mcp
python server.py

与Claude Desktop一起使用

要将此MCP服务器连接到Claude Desktop：

1. 配置Claude Desktop

编辑你的Claude Desktop配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

添加以下配置（根据系统调整路径）：

{
  "mcpServers": {
    "minio-mcp-server": {
      "command": "/Users/your_username/.local/bin/uv",
      "args": [
        "--directory",
        "/path/to/your/minio-mcp-server",
        "run",
        "python",
        "src/minio_mcp/server.py"
      ],
      "env": {
        "MINIO_ENDPOINT": "localhost:9000",
        "MINIO_ACCESS_KEY": "minioadmin",
        "MINIO_SECRET_KEY": "minioadmin",
        "MINIO_SECURE": "false"
      }
    }
  }
}

2. 重启Claude Desktop

保存配置后，完全重启Claude Desktop。

3. 测试连接

尝试以下命令：

"列出MinIO中的所有桶"
"显示'my-bucket'桶的信息"
"列出'my-bucket'中的前10个对象"
"获取'my-bucket'中'file.txt'的信息"
"从'my-bucket'中删除'old-file.txt'"

架构

核心组件

FastMCP服务器 (server.py)：主要的MCP协议处理器，使用FastMCP框架
MinioClient (infrastructure/minio_client.py)：基础设施层，负责MinIO客户端管理和配置
BucketTools (tools/bucket_tools.py)：桶操作的业务逻辑，包括验证和错误处理
ObjectTools (tools/object_tools.py)：对象操作的业务逻辑，包括全面的元数据提取
TextContent (tools/entities.py)：标准化响应实体，用于一致的错误处理

数据流

MCP客户端 → FastMCP服务器 → BucketTools/ObjectTools → MinioClient → MinIO服务器

配置选项

环境变量	描述	默认值
`MINIO_ENDPOINT`	MinIO服务器端点	必填
`MINIO_ACCESS_KEY`	认证访问密钥	必填
`MINIO_SECRET_KEY`	认证密钥	必填
`MINIO_SECURE`	使用HTTPS（true/false）	`true`
`MINIO_LOG_LEVEL`	日志级别（DEBUG/INFO/WARNING/ERROR）	`INFO`
`MINIO_MAX_OBJECTS_LIST`	每次列表操作的最大对象数	`25`

开发

设置测试MinIO服务器

docker run -p 9000:9000 -p 9001:9001 \
  --name minio-test \
  -e "MINIO_ROOT_USER=minioadmin" \
  -e "MINIO_ROOT_PASSWORD=minioadmin" \
  quay.io/minio/minio server /data --console-address ":9001"

运行测试

# 运行所有测试
uv run pytest

# 运行带有覆盖率报告的测试
uv run pytest --cov=src/minio_mcp --cov-report=html

# 运行特定测试文件
uv run pytest tests/tools/test_bucket_tools.py -v
uv run pytest tests/tools/test_object_tools.py -v
uv run pytest tests/infrastructure/test_minio_client.py -v

# 测试特定功能
uv run pytest -k "test_create_bucket" -v

代码质量

# 代码检查和格式检查
uv run ruff check src tests

# 自动格式化代码
uv run ruff format src tests

# 类型检查
uv run mypy src

许可证

[在此处添加您的许可证]

贡献

分叉仓库
创建功能分支
进行更改
为新功能添加测试
确保所有测试通过且代码质量检查成功
提交拉取请求

支持

对于问题和疑问，请查阅文档或在仓库中打开一个issue。