mspbots-fleet-mcp

MCP server for the MSPbots Fleet Platform API — a multi-tenant console over fleetdm: host inventory, on-demand scripts, and saved osquery queries, exposed to MCP clients.

It follows the same design as the sibling mspbots-agent-mcp service: stateless, no stored credentials, per-request header authentication over the Model Context Protocol (Streamable HTTP/SSE transport).

When would you use this

This MCP wraps an internal MSPbots product (device fleet management), not a third-party integration. Typical uses:

• "What hosts does this tenant have, and which are offline?" → mspbotsfleet_list_hosts

• "Tag this laptop as Production" → mspbotsfleet_set_host_labels

• "This machine looks stale, force a refresh" → mspbotsfleet_refetch_host

• "Run our log-collection script on that server" → mspbotsfleet_run_script

• "What's the disk usage across all Windows hosts right now?" → create a saved query with mspbotsfleet_create_query, then mspbotsfleet_run_query

• "A batch of new laptops just enrolled, claim the ones we declared" → mspbotsfleet_claim_hosts

• "We're offboarding this device, stop tracking it as ours (but leave it in Fleet)" → mspbotsfleet_release_host

Related MCP server: Rancher MCP Server

Tools

所有工具的凭证均来自请求头（X-MSP-Token / X-MSP-Tenant-Id / X-MSP-Host）， 工具参数里不需要传 token。

Hosts

主机无法通过接口创建：机器装上 fleetd 并注册后自动出现，再按本租户声明过的标识符 （主机名/序列号/UUID）认领归属，见 mspbotsfleet_claim_hosts。

主机列表为全量拉取后在内存过滤/排序/分页，Fleet 侧数据缓存 15 秒，归属信息实时查库不进缓存。 claim_hosts 返回 {claimed, waiting, rejected}：waiting 是已声明但主机还没出现在 Fleet 里， rejected 是标识符已被别的租户声明过。

Scripts

create_script/update_script 只返回 {id, name}，时间戳等其余字段需再查 mspbotsfleet_get_script/mspbotsfleet_list_scripts。

Saved queries

SQL 校验规则：只允许单条 SELECT 或 WITH … SELECT，末尾分号自动去除，正文中出现 ; 直接拒绝。这些校验由后端执行，本服务不重复校验。

Quick Start

Docker (recommended)

docker compose up --build

The server starts on http://localhost:8080.

Local (uv)

uv sync
python -m mspbots_fleet_mcp

Health Check

curl http://localhost:8080/health
# {"status": "ok"}

No credentials are required for the health endpoint.

授权参数说明 (Authentication)

Every request to /mcp must include the following HTTP headers (provided by the MCP caller — kept consistent with mspbots-agent-mcp / ticketqa-mcp):

Missing any of the three headers returns 401 Unauthorized.

下游 Fleet API 本身对鉴权失败（缺 token/签名错误/角色不足）统一返回 403， 不是 401——401 只发生在本服务这一层（缺 gateway header）。

Environment Variables

MCP Endpoint

POST http://localhost:8080/mcp

Connect your MCP client with:

• Transport: http (Streamable HTTP / SSE)

• Headers: X-MSP-Token, X-MSP-Tenant-Id, X-MSP-Host (all required)

测试示例 (Test Example)

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-MSP-Token: <token>" \
  -H "X-MSP-Tenant-Id: <tenant-id>" \
  -H "X-MSP-Host: https://agent.mspbots.ai" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "mspbotsfleet_list_hosts", "arguments": { "status": "online", "per_page": 10 } }
  }'

⚠️ 本仓库为公开仓库，请勿在任何提交的文件中写入真实的 token / tenant id 等敏感信息， 上面的 <token> / <tenant-id> 仅为占位符。