Come collegare ClickHouse a Cursor via MCP

💡 Niente installazione? Vai direttamente su cloud.anythingmcp.com. Accedi, clicca Connectors → ClickHouse, inserisci le credenziali, genera una MCP API key e hai finito. Niente Docker, niente git clone, niente server locale.

ClickHouse + Cursor

Fai interrogare a qualsiasi agente AI un server ClickHouse o un servizio ClickHouse Cloud in sola lettura tramite l'interfaccia HTTP: elenca database, tabelle e colonne, leggi le istruzioni CREATE, controlla le dimensioni delle tabelle, vedi le query in corso e recenti ed esegui qualsiasi SELECT. Ogni richiesta porta readonly=1, quindi è ClickHouse stesso a rifiutare le scritture.

Prerequisiti

Le istruzioni di setup complete sono incluse nel connettore stesso (visibili nello store quando lo selezioni). Le variabili d'ambiente richieste sono:

CLICKHOUSE_URL, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD

Step 1 — Ottieni le credenziali

La configurazione richiede circa 3 minuti. Ti servono l'indirizzo HTTPS di un server ClickHouse o di un servizio ClickHouse Cloud e un utente che possa leggere.

1. Inserisci in CLICKHOUSE_URL l'indirizzo dell'interfaccia HTTP con la porta. Su ClickHouse Cloud apri il servizio, fai clic su Connect, scegli HTTPS e copia l'host, ad esempio https://abc123xyz.europe-west4.gcp.clickhouse.cloud:8443. Self-hosted: https://your-host:8443, oppure http://your-host:8123 in una rete privata. Solo schema, host e porta, senza percorso.
2. Crea un utente dedicato che possa solo leggere, ad esempio CREATE USER mcp_reader IDENTIFIED BY '...'; GRANT SELECT ON analytics.* TO mcp_reader;. Per clickhouse_table_sizes, clickhouse_running_queries e clickhouse_recent_queries concedi anche GRANT SELECT ON system.parts, system.processes, system.query_log TO mcp_reader. Su ClickHouse Cloud l'utente predefinito è default.
3. Non assegnare a quell'utente un profilo di impostazioni con readonly = 2: il connettore imposta readonly=1 a ogni richiesta e con readonly = 2 ClickHouse rifiuta questa modifica. readonly = 0 o 1 funzionano entrambi.
4. Inserisci il nome utente in CLICKHOUSE_USER e la sua password in CLICKHOUSE_PASSWORD. Vengono inviati come HTTP Basic auth.
5. Solo ClickHouse Cloud: l'IP access list del servizio deve consentire l'indirizzo da cui chiama AnythingMCP.
6. Installa il connettore ed esegui clickhouse_server_info: mostra versione, uptime, fuso orario del server, l'utente collegato, il suo database predefinito e il livello readonly effettivo.

Cosa legge: i database visibili all'utente con engine e commento, le tabelle e le viste di un database (engine, righe e byte totali, dimensione leggibile, commento), le colonne di una tabella con tipo, espressione di default e appartenenza alla chiave di partizione, di ordinamento o primaria, l'istruzione CREATE di una tabella o vista (engine, ORDER BY, PARTITION BY, TTL, impostazioni, oppure la SELECT dietro una vista) e le colonne trovate per nome in tutti i database con clickhouse_search_columns. Per l'operatività: lo spazio occupato per tabella dalle parti attive, le query in esecuzione e le query concluse o fallite dal query log. clickhouse_query esegue un'istruzione di tipo SELECT, WITH, SHOW, DESCRIBE, EXPLAIN o EXISTS.

Cosa scrive: niente. Ogni richiesta porta l'impostazione readonly=1, quindi ClickHouse rifiuta INSERT, ALTER, CREATE, DROP e SET qualunque siano i grant dell'utente. Non essendoci tool di scrittura, all'installazione nessun tool è disattivato.

Come interroga l'AI: esplora con clickhouse_list_databases, clickhouse_list_tables, clickhouse_describe_table e clickhouse_show_create_table, poi filtra sulla chiave di ordinamento e sulle colonne di partizione, aggrega in SQL (count(), sum(), uniq(), quantile(0.95)(x), toStartOfDay(ts)) e chiude sempre con LIMIT. Prima di una query che potrebbe scansionare una tabella grande può eseguire EXPLAIN o EXPLAIN ESTIMATE. Una query è una sola istruzione senza clausola FORMAT e senza punto e virgola finale; database imposta il database predefinito per i nomi di tabella non qualificati.

Formati dei dati: il formato JSON restituisce meta (nomi e tipi delle colonne), data (righe), rows (numero di righe) e statistics (secondi trascorsi, righe e byte letti). clickhouse_query può rispondere anche in JSONCompact (righe come array, più compatto), CSVWithNames o TabSeparatedWithNames. Gli interi a 64 bit (UInt64, Int64) arrivano come stringhe, quindi "12345678901" è un numero. I valori DateTime sono YYYY-MM-DD hh:mm:ss nel fuso orario del server indicato da clickhouse_server_info, salvo che il tipo di colonna ne indichi un altro. Le dimensioni di formatReadableSize sono in unità binarie (KiB, MiB, GiB).

Paginazione e limiti: non c'è paginazione né un tetto di righe oltre al tuo LIMIT e al limite di dimensione delle risposte del connettore; l'intero risultato arriva in una sola risposta, quindi conviene aggregare invece di prendere righe grezze. clickhouse_search_columns restituisce fino a 500 risultati. clickhouse_recent_queries restituisce le ultime 100 query entro minutes (predefinito 60). clickhouse_running_queries mostra solo il nodo che risponde, su ClickHouse Cloud una replica del servizio. Un servizio Cloud inattivo si risveglia alla prima query, il che può richiedere fino a un minuto.

Errori comuni: il body contiene Code: <n>. DB::Exception: .... Il codice 164 (READONLY) significa che l'istruzione scrive o cambia un'impostazione. 497 (ACCESS_DENIED, HTTP 403) indica un GRANT mancante, oppure su ClickHouse Cloud un'IP access list che non consente questo server. 60 (UNKNOWN_TABLE) e 81 (UNKNOWN_DATABASE) indicano un nome sbagliato, 62 (SYNTAX_ERROR) SQL non valido, 159 o 241 un timeout o un limite di memoria: restringi la query. 401 o 516 (AUTHENTICATION_FAILED) significa utente o password errati. Se all'indirizzo non risponde nulla, di solito la porta è sbagliata o CLICKHOUSE_URL contiene un percorso.

Il connettore non inserisce, aggiorna né cancella dati, non crea né modifica tabelle e non gestisce i servizi ClickHouse Cloud (avvio, arresto, scaling, backup, costi): per questo installa il connettore separato ClickHouse Cloud.

Step 2 — Installa l'adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Step 3 — Aggiungi il connettore in Cursor

L'URL del tuo server: in AnythingMCP apri MCP Servers → il server su cui si trova questo connettore e copia il suo URL (https://cloud.anythingmcp.com/mcp/…). Usalo ovunque questa guida mostra YOUR_SERVER_ID.

Cursor legge i server MCP da ~/.cursor/mcp.json. Aggiungi questa voce:

{
  "mcpServers": {
    "anythingmcp": {
      "url": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Crea una chiave API MCP in AnythingMCP da MCP Servers → il tuo server → API keys e incollala al posto di YOUR_MCP_API_KEY.
2. Salva il file e riavvia Cursor.
3. Apri Cursor → Settings → MCP e verifica che anythingmcp sia elencato e connesso.
4. Inizia a chattare: l'agente ora può usare i tool di ClickHouse.

Tool disponibili

Esempi di prompt

• "Quali database e tabelle ci sono, e quali tabelle occupano più spazio su disco?"
• "Quanti eventi al giorno abbiamo avuto in analytics.events negli ultimi 30 giorni?"
• "Dove si trova una colonna come customer_id? Cerca in tutti i database."
• "Mostrami le query fallite nell'ultima ora con il loro codice di errore."
• "Quali sono i 10 paesi con più fatturato questo mese? Controlla prima la chiave di ordinamento così la query resta leggera."

FAQ

Cursor supporta server MCP personalizzati nel piano gratuito? Sì, MCP è disponibile nei piani Hobby, Pro e Business.

Prossimi passi

• Landing del connettore
• Collegare a Claude
• Collegare a ChatGPT
• Collegare a Gemini
• Collegare a Meta Muse
• Collegare a Microsoft Copilot