Mcp Croit Ceph

io.github.croit由 GitHub 帳號 croit 發布v0.2.16更新於 Oct 24, 2026

MCP server for Croit Ceph cluster management with dynamic OpenAPI tool generation

概覽

AI 產生的概覽

將 AI 助理連接到 Croit Ceph 叢集的 REST API,可用自然語言查看儲存池、OSD、伺服器、S3 儲存桶和日誌。

可以做什麼
  • 探索並呼叫叢集 API 端點,支援欄位篩選、過濾以及對大型回應的下鑽查詢
  • 透過自動產生的分類工具管理 Ceph 服務、儲存池、伺服器和 S3 儲存桶
  • 藉由 VictoriaLogs 整合搜尋與檢查叢集日誌,包含模式與異常辨識
  • 對大型結果集產生摘要並快取重複請求,以降低 token 消耗
適用情境
適合管理 Croit 代管 Ceph 叢集的維運人員,希望讓助理回答健康狀態、容量規劃與疑難排解問題,或執行日常讀取操作而不必在網頁介面中逐項點選。
執行需求
以 Docker 容器(映像 croit/mcp-croit-ceph)或 Python 原始碼在本機執行。需要 CROIT_HOST 叢集位址與在 Croit 網頁介面建立的 CROIT_API_TOKEN,並需能連線至叢集網路。可選設定 OPENAPI_FILE、USE_INCLUDED_API_SPEC、LOG_LEVEL 與 MCP_ARGS。
安裝前請注意
API token 依其角色授予叢集存取權限:ADMIN token 允許建立、更新與刪除操作,若無需變更請優先使用 VIEWER token。token 以環境變數形式傳入容器設定。伺服器也可用停用權限檢查的方式啟動,因而略過角色驗證。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Mcp Croit Ceph,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

MCP Croit Ceph

AI-powered management for Croit Ceph clusters via the Model Context Protocol (MCP)

Connect your AI assistant (like Claude) directly to your Croit Ceph cluster for intelligent cluster management, troubleshooting, and monitoring.

What is this?

An MCP server that gives AI assistants access to your Croit Ceph cluster's REST API. Ask your AI to:

  • "Show me all pools with errors"
  • "List OSDs on server node-5"
  • "Search logs for slow requests in the last hour"
  • "What's the cluster health status?"

The AI can then interact with your cluster through natural language.

Key Features

🚀 Smart & Efficient

  • Automatic token optimization - Responses optimized to save 80-95% on AI token costs
  • Field selection - Request only the data you need (e.g., just id + name)
  • Built-in filtering - grep-like search without multiple API calls
  • Intelligent summaries - Large datasets get smart summaries with drill-down capability

🔍 Advanced Log Search

  • Native VictoriaLogs integration for powerful log analysis
  • Natural language queries: "Find OSD failures in the last 24 hours"
  • Pattern detection and anomaly identification
  • Pre-built debug templates for common issues

🛡️ Production Ready

  • Role-based access control (ADMIN vs VIEWER)
  • Automatic API discovery from your cluster
  • Docker support with included OpenAPI spec
  • Comprehensive error handling

Quick Start

Using Docker (Recommended)

bash
docker run --rm -i \  -e CROIT_HOST="https://your-cluster.com" \  -e CROIT_API_TOKEN="your-api-token" \  croit/mcp-croit-ceph:latest

With Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

Basic configuration (fetches OpenAPI spec on startup):

json
{  "mcpServers": {    "croit-ceph": {      "command": "docker",      "args": [        "run", "--rm", "-i",        "-e", "CROIT_HOST=http://your-cluster.croit.io:8080",        "-e", "CROIT_API_TOKEN=your-api-token-here",        "croit/mcp-croit-ceph:latest"      ]    }  }}

Optimized configuration (recommended - 2s startup instead of 5s):

json
{  "mcpServers": {    "croit-ceph": {      "command": "docker",      "args": [        "run", "--rm", "-i",        "-v", "/absolute/path/to/openapi.json:/config/openapi.json:ro",        "-e", "CROIT_HOST=http://your-cluster.croit.io:8080",        "-e", "CROIT_API_TOKEN=your-api-token-here",        "-e", "OPENAPI_FILE=/config/openapi.json",        "croit/mcp-croit-ceph:latest"      ]    }  }}

With debug logging:

json
{  "mcpServers": {    "croit-ceph": {      "command": "docker",      "args": [        "run", "--rm", "-i",        "-e", "CROIT_HOST=http://your-cluster.croit.io:8080",        "-e", "CROIT_API_TOKEN=your-api-token-here",        "-e", "LOG_LEVEL=DEBUG",        "croit/mcp-croit-ceph:latest"      ]    }  }}

Note: Volume mounts require absolute paths (not ~/). To download the OpenAPI spec:

bash
curl -H "Authorization: Bearer YOUR_TOKEN" \     http://your-cluster.croit.io:8080/api/swagger.json > openapi.json

Restart Claude Desktop after changing the configuration.

Configuration

Required Environment Variables

bash
CROIT_HOST="https://your-cluster.com"      # Your Croit cluster URLCROIT_API_TOKEN="your-api-token"           # API token from Croit

Optional Environment Variables

bash
# Use local OpenAPI spec for faster startup (2s vs 5s)OPENAPI_FILE="/config/openapi.json"
# Use bundled spec (no external fetch, for offline/dev)USE_INCLUDED_API_SPEC="true"
# Logging verbosity: DEBUG, INFO, WARNING, ERRORLOG_LEVEL="INFO"
# Pass additional CLI argumentsMCP_ARGS="--no-permission-check --max-category-tools 5"

See .env.example for docker usage template.

Getting an API Token

  1. Log into your Croit cluster web interface
  2. Go to Settings → API Tokens
  3. Create a new token with appropriate permissions
  4. Copy the token and use it in your configuration

Example AI Conversations

Check cluster health:

You: "What's the current cluster status?"AI: Calls list_endpoints → Finds status endpoint → Returns health summary

Find problems:

You: "Show me all pools with errors"AI: Calls /pools with fields=["id","name","status"] and filter for errors    Returns only the 3 pools with issues (instead of all 100 pools)

Debug issues:

You: "Search logs for OSD failures in the last hour"AI: Uses croit_log_search with smart query parsing    Returns summary + drill-down capability for details

Capacity planning:

You: "Which pools are over 80% full?"AI: Gets pools → Filters by usage → Returns list with recommendations

Features in Detail

Token Optimization

The server automatically reduces AI token consumption:

Without OptimizationWith OptimizationSavings
100 pools, all fields → 4,000 tokens100 pools, id+name → 300 tokens92%
500 OSDs, full data → 15,000 tokensSmart summary → 1,000 tokens93%

How it works:

  1. Field Selection: Request only needed fields
  2. Smart Summaries: Large datasets get summaries with drill-down
  3. Caching: Repeated requests use cached data
  4. Auto-limiting: Sensible defaults prevent token explosions

Available Tools

The AI has access to these tools:

Core Tools:

  • list_endpoints - Discover available API endpoints
  • call_endpoint - Make API calls with optimization
  • search_last_result - Drill down into large responses

Category Tools (auto-generated):

  • manage_services - Ceph services
  • manage_pools - Storage pools
  • manage_servers - Cluster servers
  • manage_s3 - S3 buckets
  • And more...

Log Search:

  • croit_log_search - Advanced log analysis
  • croit_log_check - Quick log condition checks

Advanced Usage

Local Development

bash
# Clone repositorygit clone https://github.com/croit/mcp-croit-ceph.gitcd mcp-croit-ceph
# Create virtual environmentpython3 -m venv venvsource venv/bin/activate
# Install dependenciespip install -r requirements.txt
# Run directlyexport CROIT_HOST="https://your-cluster.com"export CROIT_API_TOKEN="your-token"python mcp-croit-ceph.py

Using Local OpenAPI Spec

For faster startup or offline development:

bash
# Download spec from your clustercurl -H "Authorization: Bearer $CROIT_API_TOKEN" \     https://your-cluster/api/swagger.json > openapi.json
# Use local specpython mcp-croit-ceph.py --openapi-file openapi.json

Command Line Options

bash
python mcp-croit-ceph.py \  --openapi-file openapi.json \      # Use local OpenAPI spec  --no-permission-check \            # Skip role check (faster)  --max-category-tools 5             # Limit category tools

Permissions & Security

The server respects your API token's role:

  • ADMIN: Full access to all operations
  • VIEWER: Read-only access (no create/delete/update)
  • Invalid token: Server exits with error

Admin-only categories: maintenance, servers, config, hooks

Troubleshooting

Token not working:

  • Verify token in Croit web interface
  • Check token hasn't expired
  • Ensure token has correct permissions

Connection issues:

  • Verify CROIT_HOST is correct (include https://)
  • Check network connectivity to cluster
  • Verify firewall allows connection

No tools showing:

  • Check Docker logs for errors
  • Verify OpenAPI spec is valid
  • Try --no-permission-check to test

Enable debug logging:

bash
export LOG_LEVEL=DEBUGpython mcp-croit-ceph.py

Documentation

Contributing

Contributions welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Run black formatter on Python files
  5. Submit a pull request

License

See LICENSE for details

Support


Made with ❤️ for the Ceph community

來源:README.md,提交 cebfa2e

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v0.2.16最新Sep 16, 2026

評分

已滿足適用檢查項的 40%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分

    請在儲存庫或註冊中心條目中宣告授權條款。