Doris-MCP-Lite

Um servidor MCP leve para conectar ao Apache Doris e outros bancos de dados compatíveis com MySQL, fornecendo ferramentas e prompts para aplicações LLM.

GitHub

Experimente este MCPPatrocinado

Documentação

📖 Doris-MCP-Lite

Um servidor MCP leve, projetado para conectar-se ao Apache Doris ou a outros esquemas de banco de dados compatíveis com MySQL, fornecendo ferramentas e prompts para aplicações LLM.

Este servidor permite que LLMs e clientes MCP explorem esquemas de banco de dados, executem consultas SQL somente leitura e aproveitem prompts analíticos pré-construídos — tudo por meio de uma interface MCP padronizada e segura.

[!WARNING] Esta é uma versão inicial para desenvolvedores do doris-mcp-lite. Algumas funções podem não operar corretamente e pequenos bugs podem existir. Se você tiver alguma dúvida, abra uma issue. O servidor MCP oficial do Apache Doris está disponível em apache/doris-mcp-server

🚀 Recursos

🛠️ Ferramentas

Execute consultas SQL somente leitura no seu banco de dados Doris.
Execute operações de análise de dados, como recuperar dados de uso anuais, mensais e diários.
Consulte metadados como esquemas de banco de dados, estruturas de tabelas e uso de recursos.
Pool de Conexões: gerenciamento eficiente de conexões com pooling para otimizar o desempenho.
Execução Assíncrona: suporte para execução de consultas assíncronas para melhorar a capacidade de resposta.

🧠 Prompts

Modelos de prompt integrados para ajudar LLMs a fazer perguntas analíticas.
Suporte para prompts multi-papéis para aprimorar a interação entre LLMs e o banco de dados Doris.
Suporte para prompts de análise SQL definidos pelo usuário e de uso geral.

🗂️ Recursos

Exponha o esquema do banco de dados Doris como recursos estruturados.
Permita que LLMs acessem contextualmente definições de tabelas e campos para melhorar a compreensão das consultas.

📦 Opções de Instalação

Recomendamos usar uv para gerenciar seu ambiente Python.

Opção 1: Instalar via script de shell

Recomendado para implantação pessoal e em servidor

Esta é a maneira mais fácil de instalar. Copie o arquivo setup.sh no projeto e execute-o localmente. Para mais informações, consulte: Guia de instalação do Doris MCP

Copie o setup.sh para o local.
Torne o script executável:

chmod +x setup.sh

Execute o script:

./setup.sh

O script instalará automaticamente o servidor e o ajudará na configuração da conexão com o banco de dados.

Opção 2: Instalar via `pip`

Recomendado para uso em produção

pip install doris-mcp-lite

✅ Após a instalação, a ferramenta de linha de comando do servidor estará disponível para iniciar o servidor MCP.

Opção 3: Clonar o código-fonte e instalar manualmente

Recomendado se você quiser modificar o servidor

Faça um fork e clone o repositório:

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

Configure um ambiente 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

Adicione este servidor ao seu cliente LLM ou execute o servidor:

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

Opção 4: Instalar usando uv diretamente

Para instalações editáveis locais

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

⚙️ Configuração Pós-Instalação

Passo 1: Configurar o arquivo `.env` (opcional)

Use o arquivo .env para salvar permanentemente as informações de conexão do banco de dados no servidor MCP, para que você não precise inserir a conexão do banco de dados toda vez que executar o servidor MCP com CLI. Claro, este passo não é necessário; se você estiver usando um cliente LLM compatível com MCP, também pode configurar uma conexão de banco de dados no arquivo de configuração do cliente MCP posteriormente (veja o passo 2). Siga estas etapas para concluir a configuração:

Configurar através do script de shell

Esta é a maneira mais recomendada e fácil de configurar. Consulte o Guia de instalação do Doris MCP.

Configurar manualmente no `.env`

Após a instalação, navegue até o diretório doris_mcp_lite/config/ dentro do diretório do seu projeto. Se você estiver usando pip, seu pacote será instalado nos site-packages do 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\

Você pode executar o seguinte comando para localizar o local de instalação do pip:

pip show doris-mcp-lite

Você encontrará um arquivo .env.example:

Copie .env.example para .env:

cp .env.example .env

Edite o .env para definir as informações de conexão do seu banco de dados 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] Se .env estiver ausente, o servidor tentará criá-lo automaticamente a partir de .env.example, mas você deve preencher manualmente as credenciais corretas.

Passo 2: Configurar o Cliente MCP

Para conectar este servidor a um cliente compatível com MCP (por exemplo, Claude Desktop, CherryStudio, Cline), você precisa modificar o JSON de configuração do seu cliente MCP.

Exemplo se você estiver usando CherryStudio:

nome: doris-mcp-lite
tipo: stdio
comando: caminho/absoluto/para/seu/uv
argumentos:

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

Exemplo se você estiver instalando com pip (mcp_setting.json):

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

Se você estiver instalando com código-fonte/uv ou 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"
		}
	}

}

Observe que você pode usar uv e server em vez de passar o caminho absoluto no arquivo de configuração, mas precisa garantir que uv esteja no seu PATH.

URL de Conexão

Lembre-se de substituir doris://user:pass@localhost:9030/mydb pela sua string de conexão real do banco de dados.

Para mais informações sobre como configurar seu cliente, consulte:

Para Desenvolvedores de Servidor - Model Context Protocol - Claude

Configuração e Uso do MCP | CherryStudio

✅ Agora seu cliente LLM descobrirá as ferramentas, prompts e recursos do Doris Analytics por meio do servidor MCP.

🖥️ Uso

Testando o servidor MCP (opcional)

Antes de começar, você pode executar o test.py no diretório src/doris-mcp-lite do projeto para chamar diretamente a interface funcional do servidor MCP e testar a conexão com o banco de dados, recursos, ferramentas, etc., sem usar LLM (como Claude, GPT, etc.). Você pode controlar quais funções testar passando argumentos pela linha de comando.

Teste todos os recursos expostos pelo servidor:

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

ou teste todas as ferramentas fornecidas pelo servidor:

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

ou teste a conexão com o banco de dados:

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

ou teste todas as funções de recursos, ferramentas e palavras de prompt de uma só vez:

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

Testando a conexão com o banco de dados e executando o servidor

Inicie o servidor MCP executando o comando:

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

Ou manualmente:

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

O servidor tenta imediatamente conectar-se ao banco de dados. Se a conexão for bem-sucedida, após a inicialização, você deverá ver:

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

Agora você pode usar as ferramentas e prompts dentro do seu cliente MCP.

📚 Visão Geral da Estrutura do Projeto

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

📜 Licença

Este projeto está licenciado sob a Licença MIT.

🌟 Agradecimentos

Construído usando o MCP Python SDK.
Baseado em: MCP: O Model Context Protocol, um padrão para LLMs interagirem com fontes de dados externas.
Apache Doris: Um banco de dados analítico de código aberto, de alto desempenho e tempo real.
Servidor MCP Oficial do Apache Doris: O servidor MCP oficial para Apache Doris.
PyMySQL: Uma biblioteca cliente MySQL em Python para interação com banco de dados.
Inspirado nos exemplos oficiais do MCP e nas melhores práticas.

🤝 Contribuições

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou enviar pull requests.