# 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-05-14

## 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 .
```

## 运行容器
```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)`：查询业务下主机。
- `add_host(bk_biz_id, host_innerip, host_name, cloud_id=0)`：新增测试主机。

## 能力边界

- `业务`、`集群`、`模块` 当前只支持查询，不支持创建、更新、删除。
- `集群` 和 `模块` 的查询方式是按 ID 批量查询，不支持“列出某业务下全部集群/模块”。
- 当前唯一的写入型工具是 `add_host`，用于向业务中新增测试主机。
- 以上限制来自 `bk-cmdb` 公开 API 文档与路由映射，当前未确认可直接用于 `biz/set/module` 的公开写接口。

## 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":{}}'
```