📖 Doris-MCP-Lite

A lightweight MCP server designed for connecting to Apache Doris or other MySQL compatible database schemas, providing tools and prompts for LLM applications.

This server enables LLMs and MCP clients to explore database schemas, run read-only SQL queries, and leverage pre-built analytical prompts — all through a standardized, secure MCP interface.

[!WARNING] This is an early developer version of doris-mcp-lite. Some functions may not operate properly and minor bugs may exist. If you have any quesions, please open an issue. The official Apache Doris MCP server is available at apache/doris-mcp-server

🚀 Features

🛠️ Tools

• Execute read-only SQL queries against your Doris database.
• Perform data analysis operations such as retrieving yearly, monthly, and daily usage data.
• Query metadata such as database schemas, table structures, and resource usage.
• Connection Pooling: Efficient connection management with pooling to optimize performance.
• Asynchronous Execution: Support for asynchronous query execution to improve responsiveness.

🧠 Prompts

• Built-in prompt templates to assist LLMs in asking analytics questions.
• Support for multi-role prompting to enhance the interaction between LLMs and the Doris database.
• Support for user-defined and general-purpose SQL analysis prompts.

🗂️ Resources

• Expose your Doris database schema as structured resources.
• Allow LLMs to contextually access table and field definitions to improve query understanding.

📚 Project Structure Overview

src/
└── doris_mcp_lite/
	├── config/             # Configuration files
	│   ├── __init__.py
	│   ├── config.py       # Loads environment variables
	│   ├── .env.example    # Environment variables template
	│   └── .env            # Stores your database credentials
	│
	├── db/                 # Database interaction logic
	│   ├── __init__.py
	│   ├── db.py           # Doris database connection class
	│   └── tools.py        # SQL query execution tools
	│
	├── res/                # Resource definitions (e.g., schemas)
	│   ├── __init__.py
	│   └── resources.py
	│
	├── prompts/            # Prebuilt prompt templates
	│   ├── __init__.py
	│   ├── general_prompts.py
	│   └── customize_prompts.py
	│
	├── __init__.py         # Main entry point to start the MCP server
	├── server.py           # Server launcher
	├── mcp_app.py          # MCP server instance
	└── test.py             # Unit test script
README.md                   # Documentation
INSTALL.md                  # Installation guide
LISENCE                     # Lisence
setup.sh                    # Auto setup wizard
pyproject.toml              # Project build configuration
.gitignore                  # Git ignore settings

📜 License

This project is licensed under the MIT License.

🌟Acknowledgements

• Built using the MCP Python SDK.
• Based on: MCP: The Model Context Protocol, a standard for LLMs to interact with external data sources.
• Apache Doris: An open-source, high-performance, real-time analytical database.
• Apache Doris Official MCP Server: The official MCP server for Apache Doris.
• PyMySQL: A Python MySQL client library for database interaction.
• Inspired by MCP official examples and best practices.

🤝 Contributions

Contributions are welcome! Feel free to open issues or submit pull requests.

📦 Installation Options

We recommend using uv to manage your Python environment.

Option 1: Install via shell script

Recommended for personal and server deployment

This is the easiest way to install. Please copy the setup.sh file in project and run it locally. For more information please refer: Doris MCP install guide

1. Copy the setup.sh to local.
2. Make the script executable:

chmod +x setup.sh

3. Run the script:

./setup.sh

The script will automatically install the server and help you walk through database configuration.

Option 2: Install via pip

Recommended for production usage

pip install doris-mcp-lite

✅ After installation, the command-line tool server will be available to launch the MCP server.

Option 3: Clone the source and install manually

Recommended if you want to modify the server

1. Fork and clone the repository:

git clone https://github.com/YOUR_USERNAME/doris-mcp-lite.git
cd doris-mcp-lite

1. Set up a local Python environment using uv:

uv venv # Create a virtual environment
uv sync # Install dependencies

# Activate the virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

uv pip install

1. Add this server to your LLM client or Run the server:

uv run server doris://user:pass@localhost:9030/mydb

Option 4: Install using uv directly

For local editable installations

uv pip install 'git+https://github.com/NomotoK/doris-mcp-lite.git'
uv sync
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

uv pip install -e .

uv run server doris://user:pass@localhost:9030/mydb

⚙️ Post-Installation Setup

Step 1: Configure .env file (optional)

Use the .env file to permanently save your database connection information in the MCP server, so you do not need to enter the database connection every time you run the MCP server with CLI. Of course, this step is not necessary, if you are using a MCP-capatible LLM client, you can also set up a database connection in the configuration file of the MCP client later (See step2). Please follow these steps to finish configuration:

Configure through shell script

This is the most recommended and easiest way to setup. Please refer to Doris MCP install guide.

Configure manually in .env

After installing, navigate to the doris_mcp_lite/config/ directory inside your project directory. If you are using pip, your package will be installed in Python site-packages:

• Mac/Linux: /Users/YOUR_USERNAME/.local/lib/python3.x/site-packages/doris_mcp_lite/config/

• Windows: C:\Users\YOUR_USERNAME\AppData\Local\Programs\Python\Python3x\Lib\site-packages\doris_mcp_lite\config\

You can run the following command to locate pip install location:

pip show doris-mcp-lite

You will find a .env.example file:

1. Copy .env.example to .env:

cp .env.example .env

2. Edit .env to set your Doris database connection information:

DB_HOST=your-doris-host
DB_PORT=9030
DB_USER=your-username
DB_PASSWORD=your-password
DB_NAME=your-database

MCP_SERVER_NAME=DorisAnalytics
DEBUG=false

[!NOTE] If .env is missing, the server will attempt to auto-create it from .env.example but you must manually fill in correct credentials.

Step 2: Configure MCP Client

To connect this server to an MCP-compatible client (e.g., Claude Desktop, CherryStudio, Cline), you need to modify your MCP client configuration JSON.

Example if you are using CherryStudio:

• name: doris-mcp-lite
• type: stdio
• command: absolute/path/to/your/uv
• arguments:

--directory
/Users/hailin/dev/Doris-MCP-Lite
run
server
doris://user:pass@localhost:9030/mydb

Example if you are installing with pip (mcp_setting.json):

{
  "mcpServers": {
    "DorisAnalytics": {
      "command": "server",
      "args": ["doris://user:pass@localhost:9030/mydb"],
      "transportType": "stdio"
    }
  }
}

If you are installing with source code/uv or using setup.sh:

{
"mcpServers": {
	"DorisAnalytics": {
		"disabled": false,
		"timeout": 60,
		"command": "absolute/path/to/uv",
		"args": [
			"--directory",
			"absolute/path/to/mcp/server",
			"run",
			"server"
			"doris://user:pass@localhost:9030/mydb"
		],
		"transportType": "stdio"
		}
	}

}

Note that you can use uv and server instead of passing absolute path in config file, but you need to make sure that uv is in your PATH.

Connection URL

Remember to replace doris://user:pass@localhost:9030/mydb with your actual database connection string.

For more information on how to configure your client, please refer to :

For Server Developers - Model Context Protocol - Claude

Config and Using MCP | CherryStudio

✅ Now your LLM client will discover Doris Analytics tools, prompts, and resources through the MCP server.

🖥️ Usage

Testing MCP server (optional)

Before you start, you can run the test.py in the project src/doris-mcp-lite directory to directly call the MCP Server functional interface to test database connection, resources, tools, etc. without using LLM (such as Claude, GPT, etc. models). You can control what functions to test by passing arguments through the command line.

Test all resources exposed by the server:

python test.py --server server.py --test resources

or test all the tools provided by the server:

python test.py --server server.py --test tools

or test database connection:

python test.py --server "doris://user:pass@localhost:9030/mydb" --test dbconfig

or test all functions of resources, tools, and prompt words at one time:

python test.py --server server.py --test all

Testing Database connection and run server

Launch the MCP server by running the command:

server doris://user:pass@localhost:9030/mydb

Or manually:

python -m doris_mcp_lite.server doris://user:pass@localhost:9030/mydb

The server immediately attempts to connect to the database. If the connection is successful, after startup, you should see:

🚀 Doris MCP Server is starting...
[DorisConnector] Connected to 127.0.0.1:9030
✅ Database connection successful.
[DorisConnector] Connection closed.

You can now use the tools and prompts inside your MCP client.