MaxKB Knowledge Base Retrieval MCP

An MCP service based on the MaxKB Admin API that retrieves knowledge base segments by user question. Supports vector retrieval, hybrid retrieval, and full-text retrieval. Default Top K is 10, retrieval mode is vector retrieval.

Served over Streamable HTTP by default:

• MCP endpoint: http://<host>:8000/mcp

• Health check: http://<host>:8000/health

Capabilities

search_mode (uses environment variable when not specified by the tool, defaults to vector retrieval):

• 向量 / 向量检索 / embedding

• 混合 / 混合检索 / blend

• 全量 / 全量检索 / keywords

• auto: hybrid retrieval → vector retrieval → full-text retrieval, until hits are found

When knowledge_ids is not specified, retrieval is performed across all knowledge bases in the current workspace that have a vector model configured.

Related MCP server: mcp-rag-assistant

Environment Variables

Copy the example file and modify it according to your actual environment:

cp .env.example .env

If top_n or search_mode is passed in a single search_knowledge call, it overrides the server-side defaults.

Local Startup

Requires Python 3.10+ and uv.

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

After startup:

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

• Health check: http://127.0.0.1:8000/health

• Log file: logs/mcp.log (rotated daily, retained for 7 days by default)

Client integration example:

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

Authorization can be either the raw Key or Bearer <key>.

For stdio mode:

MCP_TRANSPORT=stdio uv run maxkb-mcp

Docker Image Build

Requires Docker 20.10+.

docker build -t maxkb-mcp:latest .

For networks in China, it is recommended to specify a PyPI mirror:

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

Push to an image registry (optional):

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

Docker Deployment

docker-compose.yml does not build the image; it only starts with an existing image. Complete a local build or pull the image from a registry before deployment.

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

When using a remote image:

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

After startup:

• MCP: http://<host>:8000/mcp

• Health check: http://<host>:8000/health

• Log directory: host ./logs (container /app/logs)

After HTTPS reverse proxying, change the client url to https://your-domain/mcp.

If MaxKB is deployed on the host machine, set MAXKB_BASE_URL to http://host.docker.internal:<port>.

To stop the service:

docker-compose down

Logs

All HTTP requests and MCP tool calls are written to local logs, with Authorization redacted.

• File: {MAXKB_LOG_DIR}/mcp.log, rotated daily to mcp.log.YYYY-MM-DD

• Expired files are cleaned once at startup, then every 6 hours

• Logs older than MAXKB_LOG_RETENTION_DAYS (default 7 days) are deleted

FAQ

• No API Key provided: Pass the MaxKB user Key in the client headers.Authorization, or configure MAXKB_API_KEY in .env

• Slow build or timeout: Add --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple when building

• Container cannot reach MaxKB: Check MAXKB_BASE_URL, the network, and whether host.docker.internal is needed

• Certificate validation failure: Set MAXKB_VERIFY_SSL=false