Apache Doris MCP Server

English | 简体中文

Apache Doris MCP Server exposes read-only Apache Doris capabilities to MCP Hosts and AI agents over MCP 2026-07-28. Version 1.0 replaces a large flat tool surface with eight stable domains and fifty-five progressively disclosed child capabilities, while keeping runtime availability, authorization, input schemas, output schemas, and failure behavior explicit.

Release status

The package version is 1.0.0. MCP 2026-07-28 protocol compatibility on master is Generally Available (GA) on Streamable HTTP and stdio. This GA statement is scoped to protocol compatibility; the Python package classifier remains Beta, and the documented deployment limits still apply.

Before upgrading, read the 1.0 release notes, the 1.0 migration guide, and the generated 8-domain/55-child registry. The detailed release record is Issue #189.

Architecture at a glance

MCP Host
  -> stdio or Streamable HTTP
  -> transport security and authentication
  -> MCP protocol validation and authorization
  -> stable domain discovery
  -> route-aware Doris capability detection
  -> exact child dispatch and read-only runtime
  -> request-specific Doris route and RBAC
  -> bounded, schema-validated result

The default hierarchical mode exposes these domains:

Domain	Children	Responsibility
`doris_catalog`	5	catalogs, databases, tables, table context, size
`doris_query`	7	query, explain, profile, diagnosis, slow queries, explicit ADBC
`doris_cluster`	11	nodes, tasks, metrics, memory, cache, compaction, workloads
`doris_pipeline`	5	ingestion, materialized views, freshness, dependencies
`doris_search`	4	text/vector/hybrid search, analyzers, indexes, diagnosis
`doris_governance`	8	quality, storage, lineage, audit, UDFs, auth mapping
`doris_lakehouse`	3	external catalogs, lakehouse tables, Variant
`doris_semantic`	12	optional Apache Ossie grounding and MetricFlow consumption

Call a domain with {} to discover its authorized children and exact schemas. Call the same domain again with child_tool, arguments, and the returned manifest_version. Hosts that cannot use progressive disclosure may set MCP_TOOL_EXPOSURE_MODE=flat before startup; this exposes the same 55 children under collision-free formal names and does not restore pre-1.0 aliases.

See Architecture, Request lifecycle, and Tool domains.

Quick start

Requirements:

Python 3.12 or later;
Apache Doris 2.0.0 or later;
network access to the Doris FE MySQL endpoint, normally port 9030.

Install the pinned release:

pip install doris-mcp-server==1.0.0

doris-mcp-server starts the Server. doris-mcp-client is a separate client; the two commands are not interchangeable.

Configure a Doris route:

export DORIS_HOST=127.0.0.1
export DORIS_PORT=9030
export DORIS_USER=root
export DORIS_PASSWORD='replace-me'
export DORIS_DATABASE=information_schema

Start Streamable HTTP on loopback:

doris-mcp-server \
  --transport http \
  --host 127.0.0.1 \
  --port 3000

Endpoints:

MCP: POST http://127.0.0.1:3000/mcp
legacy MCP (opt-in): POST http://127.0.0.1:3000/mcp/legacy
liveness: GET http://127.0.0.1:3000/live
Doris-backed readiness: GET http://127.0.0.1:3000/ready

Hosts limited to handshake-era Streamable HTTP, including Dify 1.16.1 with MCP 2025-06-18, must set ENABLE_LEGACY_HTTP_ADAPTER=true and connect to /mcp/legacy. The adapter changes only the protocol boundary; it preserves the same 1.0 tools, authorization, capability gates, and read-only execution.

Or run stdio for a local Host:

doris-mcp-server --transport stdio

See the complete Quick start and Host integration guide.

Security boundary

The built-in 1.0 catalog is read-only; doris_admin is reserved and not registered.
Static tokens, JWT, external OAuth/OIDC, and Doris-backed OAuth are supported under mutually validated configuration boundaries.
Domain discovery and child execution use exact authorization identifiers.
Doris RBAC remains the final authority for visible objects and data.
SQL shape, identifiers, parameters, timeout, rows, bytes, and result schemas are bounded before data leaves the Server.
Secrets and backend errors are redacted from public results and logs.
Non-loopback HTTP requires authentication unless an explicit dangerous development override is enabled.

Read the Security and permission model and the Doris fine-grained access guide.

Reliability boundary

The Server uses deterministic manifests and errors, signed expiring cursors, route-aware capability snapshots, bounded stale fallback, request-specific connection routing, multi-FE failover, liveness/readiness separation, output Schema validation, and sanitized trace propagation. Unsupported or misconfigured capabilities remain discoverable with callable=false and fail closed when called.

Current limits include process-local Doris-backed OAuth, explicit-only ADBC that is disabled by default and fail-closed on token-bound routes, optional read-only Ossie grounding, an optional MetricFlow compiler sidecar whose SQL must execute through the bounded MCP query runtime, and best-effort native lineage delivery. See Reliability and limits.

Documentation

The root README is intentionally an entry point. The bilingual documentation system is indexed at:

Primary guides:

Development

git clone https://github.com/apache/doris-mcp-server.git
cd doris-mcp-server
uv sync --group dev
uv run pytest

Generated artifacts must remain synchronized:

uv run python generate_tool_catalog.py --check
uv lock --check

See Contributing and verification.

License

Apache License 2.0. See LICENSE.txt and NOTICE.