# bk-cmdb-mcp

**Repository Path**: aminglinux/bk-cmdb-mcp

## Basic Information

- **Project Name**: bk-cmdb-mcp
- **Description**: 蓝鲸cmdb MCP server
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-13
- **Last Updated**: 2026-07-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP Standalone CMDB Adapter

## 功能
- 查询业务列表
- 按 ID 批量查询业务下集群和模块
- 查询业务下主机及拓扑
- 查询无业务主机和资源池主机
- 按拓扑条件查询业务主机
- 新增测试主机
- 查询/加锁/解锁主机
- 主机转移到待回收模块
- 跨业务转移空闲机
- 批量删除集群

## 环境变量
- `CMDB_BASE_URL`：CMDB 服务器地址，例如 `http://172.17.0.2:8080`
- `CMDB_API_PREFIX`：API 前缀，默认 `/api/v3`
- `CMDB_USER`：CMDB 用户名，默认 `admin`
- `CMDB_SUPPLIER_ACCOUNT`：供应商 ID，默认 `0`
- `MCP_ALLOWED_HOSTS`：允许访问 MCP HTTP 入口的 Host，支持逗号分隔的主机名、IP 或 CIDR，默认 `localhost,127.0.0.1,192.168.186.0/24`

## 构建 Docker 镜像
```bash
docker build -t mcp_service:latest .
```

如需使用自定义 PyPI 镜像，可在构建时传入：

```bash
docker build \
  --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
  -t mcp_service:latest .
```

## 运行容器
```bash
docker run -d -p 8088:8088 \
  -e CMDB_BASE_URL=http://172.17.0.2:8080 \
  -e CMDB_USER=admin \
  -e CMDB_SUPPLIER_ACCOUNT=0 \
  -e MCP_ALLOWED_HOSTS=localhost,127.0.0.1,192.168.186.0/24 \
  mcp_service:latest
```

## MCP HTTP 访问

该服务使用标准 MCP Streamable HTTP transport，对外入口为：

```text
http://localhost:8088/mcp
```

局域网客户端可使用服务器 IP，例如：

```text
http://192.168.186.196:8088/mcp
```

在支持 MCP Streamable HTTP 的客户端中，将服务地址配置为上面的 URL。

## Tools

- `list_businesses(limit=20)`：查询业务列表。
- `find_sets(bk_biz_id, bk_ids)`：按集群 ID 批量查询集群，`bk_ids` 长度必须为 1 到 500。
- `find_modules(bk_biz_id, bk_ids)`：按模块 ID 批量查询模块，`bk_ids` 长度必须为 1 到 500。
- `list_hosts(bk_biz_id, limit=20)`：查询业务下主机。
- `list_hosts_with_topology(bk_biz_id, limit=20, set_property_filter=None, module_property_filter=None, host_property_filter=None, fields=None)`：查询业务下主机及其集群/模块拓扑信息。
- `list_hosts_without_business(limit=20, bk_biz_id=None, host_property_filter=None, fields=None)`：查询无业务信息主机。
- `list_resource_pool_hosts(limit=20, host_property_filter=None, fields=None)`：查询资源池主机。
- `find_hosts_by_topology(bk_biz_id, conditions, limit=20, fields=None)`：按拓扑节点条件查询业务主机。
- `add_host(bk_biz_id, host_innerip, host_name, cloud_id=0)`：新增测试主机。
- `search_host_locks(bk_host_ids)`：查询主机锁状态。
- `add_host_lock(bk_host_ids)`：为主机加锁。
- `delete_host_lock(bk_host_ids)`：解除主机锁。
- `transfer_hosts_to_recycle_module(bk_biz_id, bk_host_ids, bk_set_id=None, bk_module_id=None)`：上交主机到业务待回收模块。
- `transfer_hosts_across_business(src_bk_biz_id, dst_bk_biz_id, bk_module_id, bk_host_ids)`：跨业务转移空闲机到目标业务空闲机模块。
- `batch_delete_sets(bk_biz_id, bk_set_ids)`：批量删除业务下集群。

## 能力边界

- `业务`、`模块` 当前仍只支持查询，不支持创建、更新、删除。
- `集群` 和 `模块` 的查询方式是按 ID 批量查询，不支持“列出某业务下全部集群/模块”。
- 当前已支持部分写操作：`add_host`、`add_host_lock`、`delete_host_lock`、`transfer_hosts_to_recycle_module`、`transfer_hosts_across_business`、`batch_delete_sets`。
- `batch_delete_sets` 已开放，但集群创建/更新、模块创建/更新/删除、业务创建/更新/删除尚未纳入当前 MCP 工具。

## MCP JSON-RPC 示例

```bash
curl -X POST http://localhost:8088/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```