Doris Mcp Server

Doris MCP Server

Doris MCP (Model Context Protocol) Server is a backend service built with Python and FastAPI. It implements the MCP, allowing clients to interact with it through defined "Tools". It's primarily designed to connect to Apache Doris databases, potentially leveraging Large Language Models (LLMs) for tasks like converting natural language queries to SQL (NL2SQL), executing queries, and performing metadata management and analysis.

🚀 What's New in v0.6.0

• 🔐 Enterprise Authentication System: Revolutionary token-bound database configuration with comprehensive Token, JWT, and OAuth authentication support, enabling secure multi-tenant access with granular control switches and enterprise-grade security defaults
• ⚡ Immediate Database Validation: Real-time database configuration validation at connection time, eliminating query-time blocking and providing instant feedback for invalid configurations - achieving 100% elimination of late-stage connection failures
• 🔄 Hot Reload Configuration Management: Zero-downtime configuration updates with intelligent hot reloading of tokens.json, automatic token revalidation, and comprehensive error handling with rollback mechanisms
• 🏗️ Advanced Connection Architecture: Session caching and connection pool optimization with 60% reduction in connection overhead, intelligent pool recreation, and automatic resource management
• 🌐 Multi-Worker Scalability: True horizontal scaling with stateless multi-worker architecture, efficient load distribution, and enterprise-grade concurrent processing capabilities
• 🔒 Enhanced Security Framework: Comprehensive access control and SQL security validation with immediate validation, role-based permissions, and enhanced injection detection patterns
• 🛠️ Unified Configuration System: Streamlined configuration management with proper command-line precedence, Docker compatibility improvements, and cross-platform deployment support
• 📊 Token Management Dashboard: Complete token lifecycle management with creation, revocation, statistics, and comprehensive audit trails for enterprise token governance
• 🌐 Web-Based Management Interface: Secure localhost-only token administration with intuitive dashboard, database binding configuration, real-time operations, and enterprise-grade access controls

> 🚀 Major Milestone: v0.6.0 establishes the platform as a production-ready enterprise authentication and database management system with zero-downtime operations (hot reload + immediate validation + multi-worker scaling), advanced security controls, and comprehensive token-bound database configuration - representing a fundamental advancement in enterprise data platform capabilities.

What's Also Included from v0.5.1

• 🔥 Critical at_eof Connection Fix: Complete elimination of connection pool errors with intelligent health monitoring and self-healing recovery
• 🔧 Enterprise Logging System: Level-based file separation with automatic cleanup and millisecond precision timestamps
• 📊 Advanced Data Analytics Suite: 7 enterprise-grade data governance tools including quality analysis, lineage tracking, and performance monitoring
• 🏃‍♂️ High-Performance ADBC Integration: Apache Arrow Flight SQL support with 3-10x performance improvements for large datasets
• ⚙️ Enhanced Configuration Management: Complete ADBC configuration system with intelligent parameter validation

Core Features

• MCP Protocol Implementation: Provides standard MCP interfaces, supporting tool calls, resource management, and prompt interactions.
• Streamable HTTP Communication: Unified HTTP endpoint supporting both request/response and streaming communication for optimal performance and reliability.
• Stdio Communication: Standard input/output mode for direct integration with MCP clients like Cursor.
• Enterprise-Grade Architecture: Modular design with comprehensive functionality:
• Tools Manager: Centralized tool registration and routing with unified interfaces (doris_mcp_server/tools/tools_manager.py)
• Enhanced Monitoring Tools Module: Advanced memory tracking, metrics collection, and flexible BE node discovery with modular, extensible design
• Query Information Tools: Enhanced SQL explain and profiling with configurable content truncation, file export for LLM attachments, and advanced query analytics
• Resources Manager: Resource management and metadata exposure (doris_mcp_server/tools/resources_manager.py)
• Prompts Manager: Intelligent prompt templates for data analysis (doris_mcp_server/tools/prompts_manager.py)
• Advanced Database Features:
• Query Execution: High-performance SQL execution with advanced caching and optimization, enhanced connection stability and automatic retry mechanisms (doris_mcp_server/utils/query_executor.py)
• Security Management: Comprehensive SQL security validation with configurable blocked keywords, SQL injection protection, data masking, and unified security configuration management (doris_mcp_server/utils/security.py)
• Metadata Extraction: Comprehensive database metadata with catalog federation support (doris_mcp_server/utils/schema_extractor.py)
• Performance Analysis: Advanced column analysis, performance monitoring, and data analysis tools (doris_mcp_server/utils/analysis_tools.py)
• Catalog Federation Support: Full support for multi-catalog environments (internal Doris tables and external data sources like Hive, MySQL, etc.)
• Enterprise Security: Comprehensive security framework with authentication, authorization, SQL injection protection, and data masking capabilities with environment variable configuration support
• Web-Based Token Management: Secure localhost-only interface for complete token lifecycle management with database binding, real-time statistics, and enterprise-grade access controls (doris_mcp_server/auth/token_handlers.py)
• Unified Configuration Framework: Centralized configuration management through config.py with comprehensive validation, standardized parameter naming, and smart default database handling with automatic fallback to information_schema

System Requirements

• Python: 3.12+
• Database: Apache Doris connection details (Host, Port, User, Password, Database)

🚀 Quick Start

Installation from PyPI

# Install the latest version
pip install doris-mcp-server

# Install specific version
pip install doris-mcp-server==0.6.0

> 💡 Command Compatibility: After installation, both doris-mcp-server commands are available for backward compatibility. You can use either command interchangeably.

Start Streamable HTTP Mode (Web Service)

The primary communication mode offering optimal performance and reliability:

# Full configuration with database connection
doris-mcp-server \
    --transport http \
    --host 0.0.0.0 \
    --port 3000 \
    --db-host 127.0.0.1 \
    --db-port 9030 \
    --db-user root \
    --db-password your_password 

Start Stdio Mode (for Cursor and other MCP clients)

Standard input/output mode for direct integration with MCP clients:

# For direct integration with MCP clients like Cursor
doris-mcp-server --transport stdio

🌐 Token Management Interface (New in v0.6.0)

Access the Web-Based Token Management Dashboard for enterprise-grade token administration:

Secure Access Requirements

• Localhost Access Only: Interface restricted to 127.0.0.1 and ::1 for maximum security
• Admin Authentication: Requires TOKEN_MANAGEMENT_ADMIN_TOKEN for access
• Configuration Prerequisites:

``bash # Required environment variables ENABLE_HTTP_TOKEN_MANAGEMENT=true ENABLE_TOKEN_AUTH=true TOKEN_MANAGEMENT_ADMIN_TOKEN=your_secure_admin_token TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,::1 ``

Interface Access

# Access the token management interface
http://localhost:3000/token/management?admin_token=your_secure_admin_token

Available Operations

• 📊 Token Statistics: Real-time overview of active, expired, and total tokens
• ➕ Create Tokens:
• Basic information (ID, description, expiration)
• Database binding (host, port, user, password, database)
• Custom token values or auto-generated secure tokens
• 📋 Token Management:
• List all tokens with database binding status
• One-click token revocation
• Automated expired token cleanup
• 🔒 Enterprise Security:
• All operations require admin authentication
• Real-time IP validation
• Complete audit logging
• Automatic persistence to tokens.json

> 🔐 Security Note: The interface is designed for localhost administration only. It cannot be accessed remotely, ensuring maximum security for token management operations.

Verify Installation

# Check installation
doris-mcp-server --help

# Test HTTP mode (in another terminal)
curl http://localhost:3000/health

Environment Variables (Optional)

Instead of command-line arguments, you can use environment variables:

# Basic Database Configuration
export DORIS_HOST="127.0.0.1"
export DORIS_PORT="9030"
export DORIS_USER="root"
export DORIS_PASSWORD="your_password"

# Token Management Interface (Security-Critical)
export ENABLE_HTTP_TOKEN_MANAGEMENT=true
export ENABLE_TOKEN_AUTH=true
export TOKEN_MANAGEMENT_ADMIN_TOKEN="your_secure_admin_token"
export TOKEN_MANAGEMENT_ALLOWED_IPS="127.0.0.1,::1"

# Then start with simplified command
doris-mcp-server --transport http --host 0.0.0.0 --port 3000

Command Line Arguments

The doris-mcp-server command supports the following arguments:

| Argument | Description | Default | Required | |:---------|:------------|:--------|:---------| | --transport | Transport mode: http or stdio | http | No | | --host | HTTP server host (HTTP mode only) | 0.0.0.0 | No | | --port | HTTP server port (HTTP mode only) | 3000 | No | | --db-host | Doris database host | localhost | No | | --db-port | Doris database port | 9030 | No | | --db-user | Doris database username | root | No | | --db-password | Doris database password | - | Yes (unless in env) |

Development Setup

For developers who want to build from source:

1. Clone the Repository

# Replace with the actual repository URL if different
git clone https://github.com/apache/doris-mcp-server.git
cd doris-mcp-server

2. Install Dependencies

pip install -r requirements.txt

3. Configure Environment Variables

Copy the .env.example file to .env and modify the settings according to your environment:

cp .env.example .env

Key Environment Variables:

• Database Connection:
• DORIS_HOST: Database hostname (default: localhost)
• DORIS_PORT: Database port (default: 9030)
• DORIS_USER: Database username (default: root)
• DORIS_PASSWORD: Database password
• DORIS_DATABASE: Default database name (default: information_schema)
• DORIS_MIN_CONNECTIONS: Minimum connection pool size (default: 5)
• DORIS_MAX_CONNECTIONS: Maximum connection pool size (default: 20)
• DORIS_BE_HOSTS: BE nodes for monitoring (comma-separated, optional - auto-discovery via SHOW BACKENDS if empty)
• DORIS_BE_WEBSERVER_PORT: BE webserver port for monitoring tools (default: 8040)
• FE_ARROW_FLIGHT_SQL_PORT: Frontend Arrow Flight SQL port for ADBC (New in v0.5.0)
• BE_ARROW_FLIGHT_SQL_PORT: Backend Arrow Flight SQL port for ADBC (New in v0.5.0)
• Authentication Configuration (Enhanced in v0.6.0):
• ENABLE_TOKEN_AUTH: Enable token-based authentication (default: false)
• ENABLE_JWT_AUTH: Enable JWT authentication (default: false)
• ENABLE_OAUTH_AUTH: Enable OAuth authentication (default: false)
• ENABLE_DORIS_OAUTH_AUTH: Enable Doris-backed OAuth authentication (default: false)
• DORIS_OAUTH_BASE_URL: Public base URL used by Doris-backed OAuth discovery and token endpoints
• TOKEN_FILE_PATH: Path to tokens.json file for token management (default: tokens.json)
• TOKEN_HOT_RELOAD: Enable hot reloading of token configuration (default: true)
• DEFAULT_ADMIN_TOKEN: Default admin token (customizable via env)
• DEFAULT_ANALYST_TOKEN: Default analyst token (customizable via env)
• DEFAULT_READONLY_TOKEN: Default readonly token (customizable via env)
• Legacy Security Configuration:
• AUTH_TYPE: Legacy authentication type (token/basic/oauth, deprecated - use individual switches)
• TOKEN_SECRET: Legacy token secret key (use token-based auth instead)
• ENABLE_SECURITY_CHECK: Enable/disable SQL security validation (default: true)
• BLOCKED_KEYWORDS: Comma-separated list of blocked SQL keywords
• ENABLE_MASKING: Enable data masking (default: true)
• MAX_RESULT_ROWS: Maximum result rows (default: 10000)
• ADBC Configuration (New in v0.5.0):
• ADBC_DEFAULT_MAX_ROWS: Default maximum rows for ADBC queries (default: 100000)
• ADBC_DEFAULT_TIMEOUT: Default ADBC query timeout in seconds (default: 60)
• ADBC_DEFAULT_RETURN_FORMAT: Default return format - arrow/pandas/dict (default: arrow)
• ADBC_CONNECTION_TIMEOUT: ADBC connection timeout in seconds (default: 30)
• ADBC_ENABLED: Enable/disable ADBC tools (default: true)
• Performance Configuration:
• ENABLE_QUERY_CACHE: Enable query caching (default: true)
• CACHE_TTL: Cache time-to-live in seconds (default: 300)
• MAX_CONCURRENT_QUERIES: Maximum concurrent queries (default: 50)
• MAX_RESPONSE_CONTENT_SIZE: Maximum response content size for LLM compatibility (default: 4096, New in v0.4.0)
• Enhanced Logging Configuration (Improved in v0.5.0):
• LOG_LEVEL: Log level (DEBUG/INFO/WARNING/ERROR, default: INFO)
• LOG_FILE_PATH: Log file path (automatically organized by level)
• ENABLE_AUDIT: Enable audit logging (default: true)
• ENABLE_LOG_CLEANUP: Enable automatic log cleanup (default: true, Enhanced in v0.5.0)
• LOG_MAX_AGE_DAYS: Maximum age of log files in days (default: 30, Enhanced in v0.5.0)
• LOG_CLEANUP_INTERVAL_HOURS: Log cleanup check interval in hours (default: 24, Enhanced in v0.5.0)
• New Features in v0.5.0:
• Level-based File Separation: Automatic separation into debug.log, info.log, warning.log, error.log, critical.log
• Timestamped Format: Enhanced formatting with millisecond precision and proper alignment
• Background Cleanup Scheduler: Automatic cleanup with configurable retention policies
• Audit Trail: Dedicated audit.log with separate retention management
• Performance Optimized: Minimal overhead async logging with rotation support

Available MCP Tools

The following table lists the main tools currently available for invocation via an MCP client:

| Tool Name | Description | Parameters | |-----------------------------|--------------------------------------------------------------|--------------------------------------------------------------| | exec_query | Execute SQL query and return results. | sql (string, Required), db_name (string, Optional), catalog_name (string, Optional), max_rows (integer, Optional), timeout (integer, Optional) | | get_table_schema | Get detailed table structure information. | table_name (string, Required), db_name (string, Optional), catalog_name (string, Optional) | |

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: apache
• Source: apache/doris-mcp-server
• License: Apache-2.0
• Homepage: https://doris.apache.org

Install and usage instructions live in the source repository linked above.