AI导哈

MinIO MCP服务器

MinIO MCP服务器是一个模型上下文协议（MCP）服务器，提供MCP兼容客户端与MinIO对象存储之间的桥梁，支持无缝的桶管理和对象操作。

  • by Rafitis
  • Python
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 Rafitis/minio-mcp-server

使用说明

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）
  • 异步架构全面支持MCP协议的异步/await特性
  • 模块化设计将职责分离到 BucketTools 和 ObjectTools 类中
  • 广泛测试使用高级模拟技术实现100%测试覆盖率
  • 标准化回复通过TextContent实体实现一致的错误处理

快速入门

先决条件

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

安装

# Clone the repository
git clone <repository-url>
cd minio-mcp-server

# Install dependencies
uv sync

# Install in development mode
uv pip install -e .

配置

  1. 复制示例环境文件：
cp .env.example .env
  1. 在（相应位置）配置您的MinIO连接 .env：
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_SECURE=false
MINIO_LOG_LEVEL=INFO

运行服务器

# Start the MCP server (stdio transport for Claude Desktop)
uv run python src/minio_mcp/server.py

# Test with MCP Inspector (interactive testing)
uv run mcp src/minio_mcp/server.py

# Alternative: Direct python execution
cd src/minio_mcp
python server.py

与Claude桌面版一起使用

要将此MCP服务器与Claude桌面连接：

1. 配置Claude桌面版

编辑您的Claude桌面配置文件：

  • 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桌面版

保存配置后，请完全重启Claude桌面应用。

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): 带有验证和错误处理的桶（bucket）操作业务逻辑
  • ObjectTools（中文可译为“对象工具”或根据具体上下文可能译为“对象处理工具”等，但“对象工具”为较为通用的翻译） (tools/object_tools.py): 对象操作的业务逻辑，包含全面的元数据提取
  • 文本内容 (tools/entities.py): 标准化的响应实体，用于一致的错误处理

数据流

MCP Client → FastMCP Server → BucketTools/ObjectTools → MinioClient → MinIO Server

配置选项

环境变量 描述 默认值
（横线或分隔符） （横线或分隔符） （横线或分隔符）
MinIO 服务器终端节点 必填 MINIO_ACCESS_KEY
认证访问密钥 必填 MINIO_SECRET_KEY
用于身份验证的秘密密钥 必需 MINIO_SECURE
MINIO_LOG_LEVEL INFO 日志级别 (DEBUG/INFO/WARNING/ERROR)
MINIO_MAX_OBJECTS_LIST 25 每次列表操作的最大对象数

|

发展

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"

设置一个测试用的MinIO服务器

# Run all tests
uv run pytest

# Run with coverage report
uv run pytest --cov=src/minio_mcp --cov-report=html

# Run specific test files
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

# Test specific functionality
uv run pytest -k "test_create_bucket" -v

运行测试

# Lint and format check
uv run ruff check src tests

# Auto-format code
uv run ruff format src tests

# Type checking
uv run mypy src

代码质量

许可证

[在此添加您的许可证]

  1. 做出贡献
  2. 为仓库创建分支（或：克隆仓库）
  3. 创建一个特性分支
  4. 做出你的更改
  5. 为新功能添加测试
  6. 确保所有测试通过且代码质量检查成功

提交拉取请求

支持

相关 MCP