MaxKB 知识库检索 MCP

基于 MaxKB Admin API 的 MCP 服务，按用户问题检索知识库分段。支持向量检索、混合检索、全量检索。默认 Top K 为 10、检索模式为向量检索。

默认以 Streamable HTTP 提供服务：

• MCP 地址：http://<主机>:8000/mcp

• 健康检查：http://<主机>:8000/health

能力

search_mode（工具未指定时使用环境变量，默认向量检索）：

• 向量 / 向量检索 / embedding

• 混合 / 混合检索 / blend

• 全量 / 全量检索 / keywords

• auto：混合检索 → 向量检索 → 全文检索，直到命中

未指定 knowledge_ids 时，会在当前用户可见工作空间中所有已配置向量模型的知识库里检索。未指定 workspace_id 时，通过 GET /admin/api/user/profile 的 workspace_list 获取可见工作空间（普通用户可用），不再调用工作空间管理接口，也不会静默落到 default。

Related MCP server: mcp-rag-bridge

环境变量

复制示例文件后按实际环境修改：

cp .env.example .env

单次调用 search_knowledge 时若传入 top_n 或 search_mode，会覆盖服务端默认值。

本地启动

需要 Python 3.10+ 与 uv。

cp .env.example .env
uv sync
uv run maxkb-mcp

启动后：

• MCP：http://127.0.0.1:8000/mcp

• 健康检查：http://127.0.0.1:8000/health

• 日志文件：logs/mcp.log（按天滚动，默认保留 7 天）

客户端接入示例：

{
  "mcpServers": {
    "maxkb-knowledge": {
      "transport": "streamable_http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "你的 MaxKB API Key"
      },
      "disabled": false
    }
  }
}

Authorization 可以是原始 Key，也可以是 Bearer <key>。

API Key 优先级（HTTP / streamable_http）：

1. MCP 客户端 headers.Authorization（每次请求携带）

2. 同一 MCP 会话里缓存的 Key（后续请求未再带 Authorization 时）

3. 服务端 .env 的 MAXKB_API_KEY

.env 里 Key 为空时，第 3 步不生效，必须在 MCP 配置里传 Authorization。两边都配了则以 MCP 配置为准。

如需 stdio 模式：

MCP_TRANSPORT=stdio uv run maxkb-mcp

Docker 镜像打包

需要 Docker 20.10+。

docker build -t maxkb-mcp:latest .

国内网络建议指定 PyPI 镜像：

docker build \
  --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
  -t maxkb-mcp:latest .

推送到镜像仓库（可选）：

docker tag maxkb-mcp:latest <registry>/<namespace>/maxkb-mcp:0.1.0
docker push <registry>/<namespace>/maxkb-mcp:0.1.0

Docker 部署

docker-compose.yml 不构建镜像，只使用已有镜像启动。部署前先完成本地构建或从仓库拉取镜像。

cp .env.example .env
docker-compose up -d
docker-compose logs -f maxkb-mcp

使用远程镜像时：

MAXKB_MCP_IMAGE=<registry>/<namespace>/maxkb-mcp:0.1.0 docker-compose up -d

启动后：

• MCP：http://<主机>:8000/mcp

• 健康检查：http://<主机>:8000/health

• 日志目录：宿主机 ./logs（容器内 /app/logs）

经 HTTPS 反代后，客户端 url 改为 https://your-domain/mcp。

若 MaxKB 部署在宿主机，将 MAXKB_BASE_URL 写成 http://host.docker.internal:<端口>。

停止服务：

docker-compose down

日志

所有 HTTP 请求与 MCP 工具调用都会写入本地日志，Authorization 会脱敏。

• 文件：{MAXKB_LOG_DIR}/mcp.log，每天滚动为 mcp.log.YYYY-MM-DD

• 启动时清理一次过期文件，之后每 6 小时再清理

• 超过 MAXKB_LOG_RETENTION_DAYS（默认 7 天）的日志会被删除

常见问题

• 普通用户看不到工作空间：已改为读用户 profile 的 workspace_list，不要用工作空间管理接口

• 未提供 API Key：在客户端 headers.Authorization 中传入 MaxKB 用户 Key，或在 .env 中配置 MAXKB_API_KEY

• 构建慢或超时：打包时加 --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

• 容器访问不到 MaxKB：检查 MAXKB_BASE_URL、网络，以及是否需要 host.docker.internal

• 证书校验失败：设置 MAXKB_VERIFY_SSL=false