VISTA Data MCP Server

VISTA Data MCP Server

Read-only MCP server for querying ClickHouse (product telemetry) and Elasticsearch (download analytics). Built for Percona VISTA.

Install

curl -fsSL https://raw.githubusercontent.com/Percona-Lab/vista-data-mcp/main/install-vista-data-mcp | bash

The installer will:

1. Install uv if needed
2. Ask you to choose Remote (default) or Local mode
3. Configure Claude Desktop and Claude Code automatically
4. Install the VISTA plugin

Remote mode — connects to the shared Percona server over VPN. No credentials, no clone, no local install. Most users choose this.

Local mode — for users with their own ClickHouse or Elasticsearch credentials who want to run off-VPN (development, custom data sources).

Re-run the same command to update or change mode.

---

Tools

ClickHouse (telemetry)

| Tool | Description | |------|-------------| | query_clickhouse | Run any read-only SQL (SELECT, SHOW, DESCRIBE, EXPLAIN) | | ch_list_databases | Show all accessible databases | | ch_list_tables | Show tables in a database | | ch_describe_table | Show column names, types, and comments | | ch_sample_data | Get sample rows from a table |

Elasticsearch (downloads)

| Tool | Description | |------|-------------| | search_elasticsearch | Run an Elasticsearch query (JSON DSL) | | es_list_indices | Show all indices with doc counts and sizes | | es_get_mapping | Show field mapping (schema) for an index | | es_sample_data | Get sample documents from an index |

All results are returned as Markdown tables. Only read-only queries are allowed.

---

Manual Install (alternative)

If you prefer not to use the installer:

Claude Code (CLI)

claude mcp add vista-data \
  -e CLICKHOUSE_HOST=your-ch-host \
  -e CLICKHOUSE_PORT=8443 \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD=your-ch-password \
  -e CLICKHOUSE_DATABASE=default \
  -e CLICKHOUSE_SECURE=true \
  -e ES_HOST=your-es-host \
  -e ES_PORT=9200 \
  -e ES_USER=your-es-user \
  -e ES_PASSWORD=your-es-password \
  -e ES_SECURE=true \
  -- uvx --from git+https://github.com/Percona-Lab/vista-data-mcp vista-data-mcp

Development

git clone https://github.com/Percona-Lab/vista-data-mcp.git
cd vista-data-mcp
cp .env.example .env
# Edit .env with your credentials
uv run mcp_server.py

---

Safety

• Read-only: ClickHouse allows only SELECT, SHOW, DESCRIBE, EXPLAIN. Elasticsearch uses search API only (no indexing).
• Mutation blocking: INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE are rejected
• Row/hit limits: Results capped at 500 (configurable via CLICKHOUSE_MAX_ROWS / ES_MAX_HITS)
• Query timeout: 30 seconds default (configurable via CLICKHOUSE_QUERY_TIMEOUT / ES_QUERY_TIMEOUT)
• Identifier sanitization: Database and table names validated against injection

Environment Variables

ClickHouse

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | CLICKHOUSE_HOST | Yes* | — | ClickHouse server hostname | | CLICKHOUSE_PORT | No | 8443 | HTTP(S) port | | CLICKHOUSE_USER | No | default | Username | | CLICKHOUSE_PASSWORD | No | "" | Password | | CLICKHOUSE_DATABASE | No | default | Default database | | CLICKHOUSE_SECURE | No | true | Use HTTPS | | CLICKHOUSE_QUERY_TIMEOUT | No | 30 | Timeout in seconds | | CLICKHOUSE_MAX_ROWS | No | 500 | Max rows per query |

Elasticsearch

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | ES_HOST | Yes* | — | Elasticsearch hostname | | ES_PORT | No | 9200 | Port | | ES_USER | No | "" | Username (for basic auth) | | ES_PASSWORD | No | "" | Password | | ES_SECURE | No | true | Use HTTPS | | ES_VERIFY_CERTS | No | true | Verify SSL certificates | | ES_QUERY_TIMEOUT | No | 30 | Timeout in seconds | | ES_MAX_HITS | No | 500 | Max hits per search |

*Only required if you want to use that data source. Tools for unconfigured sources return a helpful message.

---

Part of the Alpine Toolkit

Built with CAIRN for VISTA.

License

Apache 2.0