Integrations
Uses .ENV files for flexible configuration of database connections, server settings, logging preferences, and other environment variables.
Provides tools for interacting with Apache Doris databases, enabling database metadata retrieval, SQL query execution, schema exploration, and audit log retrieval through a standardized Model Control Panel interface.
Implemented using FastAPI to provide both SSE and HTTP streaming endpoints for clients to interact with the MCP protocol, supporting tool calls and prompt interactions.
Doris MCP Server
Doris MCP (Model Control Panel) Server is a backend service built with Python and FastAPI. It implements the MCP (Model Control Panel) protocol, 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.
Core Features
- MCP Protocol Implementation: Provides standard MCP interfaces, supporting tool calls, resource management, and prompt interactions.
- Multiple Communication Modes:
- SSE (Server-Sent Events): Served via
/sse
(initialization) and/mcp/messages
(communication) endpoints (src/sse_server.py
). - Streamable HTTP: Served via the unified
/mcp
endpoint, supporting request/response and streaming (src/streamable_server.py
). - (Optional) Stdio: Interaction possible via standard input/output (
src/stdio_server.py
), requires specific startup configuration.
- SSE (Server-Sent Events): Served via
- Tool-Based Interface: Core functionalities are encapsulated as MCP tools that clients can call as needed. Currently available key tools focus on direct database interaction:
- SQL Execution (
mcp_doris_exec_query
) - Database and Table Listing (
mcp_doris_get_db_list
,mcp_doris_get_db_table_list
) - Metadata Retrieval (
mcp_doris_get_table_schema
,mcp_doris_get_table_comment
,mcp_doris_get_table_column_comments
,mcp_doris_get_table_indexes
) - Audit Log Retrieval (
mcp_doris_get_recent_audit_logs
) Note: Current tools primarily focus on direct DB operations.
- SQL Execution (
- Database Interaction: Provides functionality to connect to Apache Doris (or other compatible databases) and execute queries (
src/utils/db.py
). - Flexible Configuration: Configured via a
.env
file, supporting settings for database connections, LLM providers/models, API keys, logging levels, etc. - Metadata Extraction: Capable of extracting database metadata information (
src/utils/schema_extractor.py
).
System Requirements
- Python 3.12+
- Database connection details (e.g., Doris Host, Port, User, Password, Database)
Quick Start
1. Clone the Repository
2. Install Dependencies
3. Configure Environment Variables
Copy the .env.example
file to .env
and modify the settings according to your environment:
Key Environment Variables:
- Database Connection:
DB_HOST
: Database hostnameDB_PORT
: Database port (default 9030)DB_USER
: Database usernameDB_PASSWORD
: Database passwordDB_DATABASE
: Default database name
- Server Configuration:
SERVER_HOST
: Host address the server listens on (default0.0.0.0
)SERVER_PORT
: Port the server listens on (default3000
)ALLOWED_ORIGINS
: CORS allowed origins (comma-separated,*
allows all)MCP_ALLOW_CREDENTIALS
: Whether to allow CORS credentials (defaultfalse
)
- Logging Configuration:
LOG_DIR
: Directory for log files (default./logs
)LOG_LEVEL
: Log level (e.g.,INFO
,DEBUG
,WARNING
,ERROR
, defaultINFO
)CONSOLE_LOGGING
: Whether to output logs to the console (defaultfalse
)
Available MCP Tools
The following table lists the main tools currently available for invocation via an MCP client:
Tool Name | Description | Parameters | Status |
---|---|---|---|
mcp_doris_get_db_list | Get a list of all database names on the server. | random_string (string, Required) | ✅ Active |
mcp_doris_get_db_table_list | Get a list of all table names in the specified database. | random_string (string, Required), db_name (string, Optional, defaults to current db) | ✅ Active |
mcp_doris_get_table_schema | Get detailed structure of the specified table. | random_string (string, Required), table_name (string, Required), db_name (string, Optional) | ✅ Active |
mcp_doris_get_table_comment | Get the comment for the specified table. | random_string (string, Required), table_name (string, Required), db_name (string, Optional) | ✅ Active |
mcp_doris_get_table_column_comments | Get comments for all columns in the specified table. | random_string (string, Required), table_name (string, Required), db_name (string, Optional) | ✅ Active |
mcp_doris_get_table_indexes | Get index information for the specified table. | random_string (string, Required), table_name (string, Required), db_name (string, Optional) | ✅ Active |
mcp_doris_exec_query | Execute SQL query and return result command. | random_string (string, Required), sql (string, Required), db_name (string, Optional), max_rows (integer, Optional, default 100), timeout (integer, Optional, default 30) | ✅ Active |
mcp_doris_get_recent_audit_logs | Get audit log records for a recent period. | random_string (string, Required), days (integer, Optional, default 7), limit (integer, Optional, default 100) | ✅ Active |
Note: All tools require a random_string
parameter as a call identifier, typically handled automatically by the MCP client. "Optional" and "Required" refer to the tool's internal logic; the client might need to provide values for all parameters depending on its implementation. The tool names listed here are the base names; clients might see them prefixed (e.g., mcp_doris_stdio3_get_db_list
) depending on the connection mode.
4. Run the Service
If you use SSE mode, execute the following command:
This command starts the FastAPI application, providing both SSE and Streamable HTTP MCP services by default.
Service Endpoints:
- SSE Initialization:
http://<host>:<port>/sse
- SSE Communication:
http://<host>:<port>/mcp/messages
(POST) - Streamable HTTP:
http://<host>:<port>/mcp
(Supports GET, POST, DELETE, OPTIONS) - Health Check:
http://<host>:<port>/health
- (Potential) Status Check:
http://<host>:<port>/status
(Confirm if implemented inmain.py
)
Usage
Interaction with the Doris MCP Server requires an MCP Client. The client connects to the server's SSE or Streamable HTTP endpoints and sends requests (like tool_call
) according to the MCP specification to invoke the server's tools.
Main Interaction Flow:
- Client Initialization: Connect to
/sse
(SSE) or send aninitialize
method call to/mcp
(Streamable). - (Optional) Discover Tools: The client can call
mcp/listTools
ormcp/listOfferings
to get the list of supported tools, their descriptions, and parameter schemas. - Call Tool: The client sends a
tool_call
message/request, specifying thetool_name
andarguments
.- Example: Get Table Schema
tool_name
:mcp_doris_get_table_schema
(or the mode-specific name)arguments
: Includerandom_string
,table_name
,db_name
.
- Example: Get Table Schema
- Handle Response:
- Non-streaming: The client receives a response containing
result
orerror
. - Streaming: The client receives a series of
tools/progress
notifications, followed by a final response containing theresult
orerror
.
- Non-streaming: The client receives a response containing
Specific tool names and parameters should be referenced from the src/tools/
code or obtained via MCP discovery mechanisms.
Connecting with Cursor
You can connect Cursor to this MCP server using either Stdio or SSE mode.
Stdio Mode
Stdio mode allows Cursor to manage the server process directly. Configuration is done within Cursor's MCP Server settings file (typically ~/.cursor/mcp.json
or similar).
If you use stdio mode, please execute the following command to download and build the environment dependency package, but please note that you need to change the project path to the correct path address:
- Configure Cursor: Add an entry like the following to your Cursor MCP configuration:Copy
- Key Points:
- Replace
/path/to/your/doris-mcp
with the actual absolute path to the project's root directory on your system. The--project
argument is crucial foruv
to find thepyproject.toml
and run the correct command. - The
command
is set touv
(assuming you useuv
for package management as indicated byuv.lock
). Theargs
include--project
, the path,run
, andmcp-doris
(which should correspond to a script defined in yourpyproject.toml
). - Database connection details (
DB_HOST
,DB_PORT
,DB_USER
,DB_PASSWORD
,DB_DATABASE
) are set directly in theenv
block within the configuration file. Cursor will pass these to the server process. No.env
file is needed for this mode when configured via Cursor.
- Replace
SSE Mode
SSE mode requires you to run the MCP server independently first, and then tell Cursor how to connect to it.
- Configure
.env
: Ensure your database credentials and any other necessary settings (likeSERVER_PORT
if not using the default 3000) are correctly configured in the.env
file within the project directory. - Start the Server: Run the server from your terminal in the project's root directory:This script typically reads theCopy
.env
file and starts the FastAPI server in SSE mode (check the script andsse_server.py
/main.py
for specifics). Note the host and port the server is listening on (default is0.0.0.0:3000
). - Configure Cursor: Add an entry like the following to your Cursor MCP configuration, pointing to the running server's SSE endpoint:Note: The example uses the default portCopy
3000
. If your server is configured to run on a different port (like3010
in the user example), adjust the URL accordingly.
After configuring either mode in Cursor, you should be able to select the server (e.g., doris-stdio
or doris-sse
) and use its tools.
Directory Structure
Developing New Tools
This section outlines the process for adding new MCP tools to the Doris MCP Server, considering the current project structure.
1. Leverage Utility Modules
Before writing new database interaction logic from scratch, check the existing utility modules:
doris_mcp_server/utils/db.py
: Provides basic functions for getting database connections (get_db_connection
) and executing raw queries (execute_query
,execute_query_df
).doris_mcp_server/utils/schema_extractor.py
(MetadataExtractor
class): Offers high-level methods to retrieve database metadata, such as listing databases/tables (get_all_databases
,get_database_tables
), getting table schemas/comments/indexes (get_table_schema
,get_table_comment
,get_column_comments
,get_table_indexes
), and accessing audit logs (get_recent_audit_logs
). It includes caching mechanisms.doris_mcp_server/utils/sql_executor_tools.py
(execute_sql_query
function): Provides a wrapper arounddb.execute_query
that includes security checks (optional, controlled byENABLE_SQL_SECURITY_CHECK
env var), adds automaticLIMIT
to SELECT queries, handles result serialization (dates, decimals), and formats the output into the standard MCP success/error structure. It's recommended to use this for executing user-provided or generated SQL.
You can import and combine functionalities from these modules to build your new tool.
2. Implement Tool Logic
Implement the core logic for your new tool as an async
function within doris_mcp_server/tools/mcp_doris_tools.py
. This keeps the primary tool implementations centralized. Ensure your function returns data in a format that can be easily wrapped into the standard MCP response structure (see _format_response
in the same file for reference).
Example: Let's create a simple tool get_server_time
.
3. Register the Tool (Dual Registration)
Due to the separate handling of SSE/Streamable and Stdio modes, you need to register the tool in two places:
A. SSE/Streamable Registration (tool_initializer.py
)
- Import your new tool function from
mcp_doris_tools.py
. - Inside the
register_mcp_tools
function, add a new wrapper function decorated with@mcp.tool()
. - The wrapper function should call your core tool function.
- Define the tool name and provide a detailed description (including parameters if any) in the decorator. Remember to include the mandatory
random_string
parameter description for client compatibility, even if your wrapper doesn't explicitly use it.
Example (tool_initializer.py
):
B. Stdio Registration (mcp_core.py
)
- Similar to SSE, add a new wrapper function decorated with
@stdio_mcp.tool()
. - Important: Import your core tool function (
mcp_doris_get_server_time
) inside the wrapper function (delayed import pattern used in this file). - The wrapper calls the core tool function. The wrapper itself might need to be
async def
depending on howFastMCP
handles tools in Stdio mode, even if the underlying function is simple (as seen in the current file structure). Ensure the call matches (e.g., useawait
if calling an async function).
Example (mcp_core.py
):
4. Restart and Test
After implementing and registering the tool in both files, restart the MCP server (both SSE mode via ./start_server.sh
and ensure the Stdio command used by Cursor is updated if necessary) and test the new tool using your MCP client (like Cursor) in both connection modes.
Contributing
Contributions are welcome via Issues or Pull Requests.
License
This project is licensed under the Apache 2.0 License. See the LICENSE file (if it exists) for details.
You must be authenticated.
Tools
Backend service implementing the Model Control Panel protocol that connects to Apache Doris databases, allowing users to execute SQL queries, manage metadata, and potentially leverage LLMs for tasks like natural language to SQL conversion.
- Core Features
- System Requirements
- Quick Start
- Usage
- Connecting with Cursor
- Directory Structure
- Developing New Tools
- Contributing
- License
Related Resources
Related MCP Servers
- -securityAlicense-qualityA Model Context Protocol server that provides access to BigQuery. This server enables LLMs to inspect database schemas and execute queries.Last updated -63PythonMIT License
- AsecurityAlicenseAqualityA Model Context Protocol server that enables LLMs to interact with Salesforce data through SOQL queries, SOSL searches, and various API operations including record management.Last updated -1053PythonMIT License
- -securityFlicense-qualityA Model Context Protocol server providing both read and write access to PostgreSQL databases, enabling LLMs to query data, modify records, and manage database schemas.Last updated -4JavaScript
ZenML MCP Serverofficial
-securityFlicense-qualityA server implementing Model Context Protocol that enables LLMs to interact with the ZenML platform, providing access to pipeline data, stack information, and the ability to trigger new pipeline runs.Last updated -13Python