Doris-MCP-Lite

Un servidor MCP ligero para conectarse a Apache Doris y otras bases de datos compatibles con MySQL, que proporciona herramientas y avisos para aplicaciones LLM.

GitHub

Prueba este MCPPatrocinado

Documentación

📖 Doris-MCP-Lite

Un servidor MCP ligero diseñado para conectarse a Apache Doris u otros esquemas de bases de datos compatibles con MySQL, proporcionando herramientas y prompts para aplicaciones LLM.

Este servidor permite a los LLM y clientes MCP explorar esquemas de bases de datos, ejecutar consultas SQL de solo lectura y aprovechar prompts analíticos predefinidos, todo a través de una interfaz MCP estandarizada y segura.

[!WARNING] Esta es una versión temprana de desarrollo de doris-mcp-lite. Algunas funciones pueden no funcionar correctamente y pueden existir errores menores. Si tienes alguna pregunta, abre un issue. El servidor MCP oficial de Apache Doris está disponible en apache/doris-mcp-server

🚀 Características

🛠️ Herramientas

Ejecutar consultas SQL de solo lectura contra tu base de datos Doris.
Realizar operaciones de análisis de datos como recuperar datos de uso anual, mensual y diario.
Consultar metadatos como esquemas de bases de datos, estructuras de tablas y uso de recursos.
Pool de conexiones: Gestión eficiente de conexiones con pooling para optimizar el rendimiento.
Ejecución asíncrona: Soporte para ejecución de consultas asíncronas para mejorar la capacidad de respuesta.

🧠 Prompts

Plantillas de prompt integradas para ayudar a los LLM a hacer preguntas analíticas.
Soporte para prompting multi-rol para mejorar la interacción entre los LLM y la base de datos Doris.
Soporte para prompts de análisis SQL definidos por el usuario y de propósito general.

🗂️ Recursos

Exponer el esquema de tu base de datos Doris como recursos estructurados.
Permitir a los LLM acceder contextualmente a las definiciones de tablas y campos para mejorar la comprensión de las consultas.

📦 Opciones de Instalación

Recomendamos usar uv para gestionar tu entorno Python.

Opción 1: Instalar mediante script de shell

Recomendado para despliegue personal y de servidor

Esta es la forma más fácil de instalar. Por favor, copia el archivo setup.sh del proyecto y ejecútalo localmente. Para más información, consulta: Guía de instalación de Doris MCP

Copia el setup.sh a tu máquina local.
Haz que el script sea ejecutable:

chmod +x setup.sh

Ejecuta el script:

./setup.sh

El script instalará automáticamente el servidor y te guiará a través de la configuración de la base de datos.

Opción 2: Instalar mediante `pip`

Recomendado para uso en producción

pip install doris-mcp-lite

✅ Después de la instalación, la herramienta de línea de comandos estará disponible para lanzar el servidor MCP.

Opción 3: Clonar el código fuente e instalar manualmente

Recomendado si quieres modificar el servidor

Haz un fork y clona el repositorio:

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

Configura un entorno Python local usando 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

Añade este servidor a tu cliente LLM o ejecuta el servidor:

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

Opción 4: Instalar usando uv directamente

Para instalaciones editables locales

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

⚙️ Configuración Post-Instalación

Paso 1: Configurar el archivo `.env` (opcional)

Usa el archivo .env para guardar permanentemente la información de conexión a la base de datos en el servidor MCP, de modo que no necesites ingresar la conexión cada vez que ejecutes el servidor MCP con CLI. Por supuesto, este paso no es necesario, si estás usando un cliente LLM compatible con MCP, también puedes configurar una conexión a la base de datos en el archivo de configuración del cliente MCP más tarde (ver paso 2). Sigue estos pasos para completar la configuración:

Configurar mediante script de shell

Esta es la forma más recomendada y fácil de configurar. Consulta la Guía de instalación de Doris MCP.

Configurar manualmente en `.env`

Después de instalar, navega al directorio doris_mcp_lite/config/ dentro de tu directorio de proyecto. Si estás usando pip, tu paquete se instalará en los site-packages de Python:

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\

Puedes ejecutar el siguiente comando para localizar la ubicación de instalación de pip:

pip show doris-mcp-lite

Encontrarás un archivo .env.example:

Copia .env.example a .env:

cp .env.example .env

Edita .env para configurar la información de conexión de tu base de datos Doris:

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] Si .env falta, el servidor intentará crearlo automáticamente desde .env.example pero debes completar manualmente las credenciales correctas.

Paso 2: Configurar el Cliente MCP

Para conectar este servidor a un cliente compatible con MCP (por ejemplo, Claude Desktop, CherryStudio, Cline), necesitas modificar el JSON de configuración de tu cliente MCP.

Ejemplo si usas CherryStudio:

nombre: doris-mcp-lite
tipo: stdio
comando: ruta/absoluta/a/tu/uv
argumentos:

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

Ejemplo si instalas con pip (mcp_setting.json):

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

Si instalas con código fuente/uv o usando 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"
		}
	}

}

Nota que puedes usar uv y server en lugar de pasar la ruta absoluta en el archivo de configuración, pero debes asegurarte de que uv esté en tu PATH.

URL de conexión

Recuerda reemplazar doris://user:pass@localhost:9030/mydb con tu cadena de conexión real a la base de datos.

Para más información sobre cómo configurar tu cliente, consulta:

Para desarrolladores de servidores - Model Context Protocol - Claude

Config y uso de MCP | CherryStudio

✅ Ahora tu cliente LLM descubrirá las herramientas, prompts y recursos de Doris Analytics a través del servidor MCP.

🖥️ Uso

Probar el servidor MCP (opcional)

Antes de comenzar, puedes ejecutar el test.py en el directorio src/doris-mcp-lite del proyecto para llamar directamente a la interfaz funcional del servidor MCP y probar la conexión a la base de datos, recursos, herramientas, etc., sin usar un LLM (como Claude, GPT, etc.). Puedes controlar qué funciones probar pasando argumentos a través de la línea de comandos.

Probar todos los recursos expuestos por el servidor:

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

o probar todas las herramientas proporcionadas por el servidor:

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

o probar la conexión a la base de datos:

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

o probar todas las funciones de recursos, herramientas y palabras de prompt a la vez:

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

Probar la conexión a la base de datos y ejecutar el servidor

Lanza el servidor MCP ejecutando el comando:

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

O manualmente:

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

El servidor intenta inmediatamente conectarse a la base de datos. Si la conexión es exitosa, después del inicio deberías ver:

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

Ahora puedes usar las herramientas y prompts dentro de tu cliente MCP.

📚 Resumen de la Estructura del Proyecto

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

📜 Licencia

Este proyecto está licenciado bajo la Licencia MIT.

🌟 Agradecimientos

Construido usando el MCP Python SDK.
Basado en: MCP: El Protocolo de Contexto de Modelo, un estándar para que los LLM interactúen con fuentes de datos externas.
Apache Doris: Una base de datos analítica de código abierto, de alto rendimiento y en tiempo real.
Servidor MCP oficial de Apache Doris: El servidor MCP oficial para Apache Doris.
PyMySQL: Una biblioteca cliente de Python MySQL para la interacción con bases de datos.
Inspirado por los ejemplos oficiales de MCP y las mejores prácticas.

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Siéntete libre de abrir issues o enviar pull requests.