ClickHouse

Servidor MCP do ClickHouse

Um projeto de servidor MCP para banco de dados ClickHouse.

Instalação

Você pode instalar o pacote usando uv:

uv pip install clickhouse-mcp-server

Ou usando pip:

pip install clickhouse-mcp-server

Componentes

Ferramentas

O servidor fornece duas ferramentas:

• connect_database: Conecta a um banco de dados ClickHouse específico

  • Parâmetro database: Nome do banco de dados para conectar (string)
  • Retorna uma mensagem de confirmação quando a conexão é bem-sucedida

• execute_query: Executa consultas ClickHouse

  • Parâmetro query: Consulta(s) SQL para executar (string)
  • Retorna resultados da consulta em formato JSON
  • Múltiplas consultas podem ser enviadas separadas por ponto e vírgula

Configuração

O servidor usa as seguintes variáveis de ambiente:

• CLICKHOUSE_HOST: Endereço do servidor ClickHouse (padrão: "localhost")
• CLICKHOUSE_USER: Nome de usuário do ClickHouse (padrão: "root")
• CLICKHOUSE_PASSWORD: Senha do ClickHouse (padrão: "")
• CLICKHOUSE_DATABASE: Banco de dados inicial (opcional)
• CLICKHOUSE_READONLY: Modo somente leitura (defina como 1/true para ativar, padrão: false)

Início rápido

Instalação

Claude Desktop

MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "clickhouse-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/burakdirin/Projects/clickhouse-mcp-server",
        "run",
        "clickhouse-mcp-server"
      ],
      "env": {
        "CLICKHOUSE_HOST": "localhost",
        "CLICKHOUSE_USER": "root",
        "CLICKHOUSE_PASSWORD": "password",
        "CLICKHOUSE_DATABASE": "[optional]",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "clickhouse-mcp-server": {
      "command": "uvx",
      "args": [
        "clickhouse-mcp-server"
      ],
      "env": {
        "CLICKHOUSE_HOST": "localhost",
        "CLICKHOUSE_USER": "root",
        "CLICKHOUSE_PASSWORD": "password",
        "CLICKHOUSE_DATABASE": "[optional]",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}

Instalando via Smithery

Para instalar o Servidor de Integração do Banco de Dados ClickHouse para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @burakdirin/clickhouse-mcp-server --client claude

Desenvolvimento

Compilação e Publicação

Para preparar o pacote para distribuição:

1. Sincronize as dependências e atualize o arquivo de bloqueio:

uv sync

2. Compile as distribuições do pacote:

uv build

Isso criará distribuições de origem e wheel no diretório dist/.

3. Publique no PyPI:

uv publish

Observação: Você precisará definir as credenciais do PyPI via variáveis de ambiente ou flags de comando:

• Token: --token ou UV_PUBLISH_TOKEN
• Ou nome de usuário/senha: --username/UV_PUBLISH_USERNAME e --password/UV_PUBLISH_PASSWORD

Depuração

Como os servidores MCP são executados via stdio, a depuração pode ser desafiadora. Para a melhor experiência de depuração, recomendamos fortemente o uso do MCP Inspector.

Você pode iniciar o MCP Inspector via npm com este comando:

npx @modelcontextprotocol/inspector uv --directory /Users/burakdirin/Projects/clickhouse-mcp-server run clickhouse-mcp-server

Ao iniciar, o Inspector exibirá uma URL que você pode acessar no seu navegador para começar a depurar.