@futuretea/clickhouse-mcp-server 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 futuretea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# ClickHouse MCP Server
+
+[中文文档](README.zh.md)
+
+A small, read-only MCP server for exploring ClickHouse from an AI client or the command line. It connects to ClickHouse only over HTTP(S) through [`clickhouse-go/v2`](https://github.com/ClickHouse/clickhouse-go), and exposes Streamable HTTP at `/mcp`.
+
+The MCP service has no authentication. It listens on `127.0.0.1` by default. Keep it on a trusted local network unless you separately design the authentication and network boundary.
+
+## Quick start
+
+1. Copy the example configuration and set the ClickHouse HTTP address.
+
+   ```bash
+   cp config.example.yaml config.yaml
+   ```
+
+2. Build and start the HTTP server.
+
+   ```bash
+   make build
+   ./bin/clickhouse-mcp-server mcp --config config.yaml --port 8080
+   ```
+
+3. Confirm that the process is healthy.
+
+   ```bash
+   curl -s http://127.0.0.1:8080/healthz
+   # healthy
+   ```
+
+4. Configure an MCP client with the Streamable HTTP endpoint.
+
+   ```json
+   {
+     "mcpServers": {
+       "clickhouse": {
+         "url": "http://127.0.0.1:8080/mcp"
+       }
+     }
+   }
+   ```
+
+## Tools
+
+All successful tool calls return JSON in MCP text content.
+
+| Tool | Input | Result |
+|------|-------|--------|
+| `clickhouse_list_databases` | none | `{"databases":["default"]}` |
+| `clickhouse_list_tables` | optional `database` | database name plus table name, engine, and comment |
+| `clickhouse_describe_table` | required `table`, optional `database` | column name, type, defaults, and comment |
+| `clickhouse_query` | required `query`, optional positive integer `max_rows` | columns, display-string rows, returned `row_count`, and `truncated` |
+
+`clickhouse_query` defaults to 1,000 rows. The server reads one additional row to report `truncated: true`; that extra row is not returned. Each non-null cell is rendered as a string so clients receive a stable JSON shape.
+
+The query tool accepts exactly one statement. Semicolons in strings, quoted identifiers, and SQL comments are allowed; a second statement is rejected before it reaches ClickHouse. Every query is sent with ClickHouse `readonly=1`, so ClickHouse rejects writes and DDL for a user that honors that setting. The connected ClickHouse user should still have only the privileges appropriate for read access.
+
+## Configuration
+
+Configuration priority is **flags > environment variables > YAML file > defaults**. `clickhouse.address` is required and must be a `host:port` value without a scheme or path.
+
+```yaml
+port: 8080
+listen: 127.0.0.1
+log_level: info
+clickhouse:
+  address: 127.0.0.1:8123
+  database: default
+  secure: false
+  username: ""
+  password: ""
+```
+
+| Group | YAML key | Environment variable | Default | Meaning |
+|-------|----------|----------------------|---------|---------|
+| ClickHouse connection | `clickhouse.address` | `MCP_CLICKHOUSE_ADDRESS` | none | Required ClickHouse `host:port` address |
+| ClickHouse connection | `clickhouse.database` | `MCP_CLICKHOUSE_DATABASE` | `default` | Default database for table tools |
+| ClickHouse connection | `clickhouse.secure` | `MCP_CLICKHOUSE_SECURE` | `false` | Use HTTPS instead of HTTP to ClickHouse |
+| ClickHouse connection | `clickhouse.username` | `MCP_CLICKHOUSE_USERNAME` | empty | Optional ClickHouse username |
+| ClickHouse connection | `clickhouse.password` | `MCP_CLICKHOUSE_PASSWORD` | empty | Optional ClickHouse password |
+| Server | `port` | `MCP_PORT` | `0` | HTTP port; `0` starts stdio mode |
+| Server | `listen` | `MCP_LISTEN` | `127.0.0.1` | HTTP listen host |
+| Server | `sse_base_url` | `MCP_SSE_BASE_URL` | empty | Public base URL for legacy SSE message endpoints |
+| Server | `log_level` | `MCP_LOG_LEVEL` | `info` | Server log level |
+| Tool filters | `enabled_tools` | `MCP_ENABLED_TOOLS` | empty | Comma-separated tool names to enable |
+| Tool filters | `disabled_tools` | `MCP_DISABLED_TOOLS` | empty | Comma-separated tool names to disable |
+| Tool filters | `enabled_domains` | `MCP_ENABLED_DOMAINS` | empty | Comma-separated tool domains to enable |
+| Tool filters | `disabled_domains` | `MCP_DISABLED_DOMAINS` | empty | Comma-separated tool domains to disable |
+
+The server never logs the configured password. `secure: true` protects the connection to ClickHouse; it does not add TLS or authentication to the MCP HTTP endpoint.
+
+### Environment-only configuration check
+
+For the smallest local setup, set just the ClickHouse HTTP address and inspect the effective configuration. This command does not start MCP or access the network.
+
+```bash
+export MCP_CLICKHOUSE_ADDRESS=127.0.0.1:8123
+./bin/clickhouse-mcp-server config check
+```
+
+The command prints the 13 configuration fields in a stable order with their source (`flag`, `environment`, `YAML`, or `default`). Passwords are reported only as `set` or `unset`. `sse_base_url` removes query and fragment values and redacts URL userinfo before display.
+
+Use `--connect` only when you intentionally want one ClickHouse HTTP(S) `Ping`; it opens, pings, and closes a short-lived connection without starting the MCP server.
+
+```bash
+./bin/clickhouse-mcp-server config check --connect
+```
+
+## CLI
+
+The CLI uses the same configuration and is useful for checking connectivity without an MCP client.
+
+```bash
+./bin/clickhouse-mcp-server tools list --config config.yaml
+./bin/clickhouse-mcp-server tools describe clickhouse_query --config config.yaml --json
+./bin/clickhouse-mcp-server tools call clickhouse_list_databases --config config.yaml
+./bin/clickhouse-mcp-server tools call clickhouse_query --config config.yaml \
+  --params '{"query":"SELECT version()"}'
+```
+
+## Transports
+
+`mcp` starts stdio when `port` is `0`, or an HTTP process when it is non-zero. HTTP mode exposes:
+
+| Path | Purpose |
+|------|---------|
+| `/mcp` | Primary Streamable HTTP MCP endpoint |
+| `/healthz` | Health check (`GET` and `HEAD`) |
+| `/sse` | Legacy SSE MCP endpoint |
+| `/message` | SSE message endpoint |
+
+## Docker
+
+```bash
+make docker
+docker run --rm -p 8080:8080 \
+  -v "$PWD/config.yaml:/config.yaml:ro" \
+  clickhouse-mcp-server:dev --config /config.yaml --port 8080
+```
+
+Do not publish the unauthenticated HTTP port directly to the internet.
+
+## Release artifacts
+
+Only stable `vX.Y.Z` Git tags trigger releases. A validated stable release updates the npm, Docker, and GitHub Release `latest` pointers; use a versioned reference when you need a fixed version.
+
+```bash
+npx -y @futuretea/clickhouse-mcp-server
+npx -y @futuretea/clickhouse-mcp-server@<version>
+docker run --rm -i ghcr.io/futuretea/clickhouse-mcp-server:latest
+docker run --rm -i ghcr.io/futuretea/clickhouse-mcp-server:v<version>
+```
+
+Both commands launch the `mcp` command. Arguments after the package or image are forwarded to it. Maintainers need a GitHub Actions `NPM_TOKEN` with publish permission for `@futuretea`; after the first release, set the GHCR package visibility to public.
+
+## Troubleshooting
+
+- `clickhouse.address is required`: add a `host:port` value such as `127.0.0.1:8123` to the configuration or `MCP_CLICKHOUSE_ADDRESS`.
+- Connection failure: check the address, `secure` value, ClickHouse HTTP port, and network reachability.
+- Query rejection: verify the statement is a single read-only query and that the configured ClickHouse user has access to the database.
+- `truncated: true`: lower the result size in SQL or increase `max_rows` deliberately.
+
+## Development
+
+```bash
+make format
+make lint
+make test
+make ci
+```
+
+### Optional ClickHouse integration test
+
+The default test suite has no external dependency. The opt-in integration test starts an isolated local ClickHouse Docker container to verify database discovery, parameterized table inspection, `SELECT`, and that `readonly=1` rejects temporary DDL. It also builds the public server binary, starts it in HTTP mode on loopback, checks `/healthz`, and calls `tools/list` and `tools/call` through `/mcp`.
+
+```bash
+make test-integration
+```
+
+The target requires Docker and `curl`, creates a random loopback port, waits for ClickHouse health, and removes its container on exit. Set `CLICKHOUSE_INTEGRATION_IMAGE` to test another isolated image. It runs the full MCP HTTP E2E test, the read-only toolset integration test, and `config check --connect`. It is local-only: neither `make test` nor the GitHub Actions CI workflow runs it.
+
+The repository retains its template assets under `scripts/` and `templates/` for local reference; they are not part of the ClickHouse server runtime.
+
+## License
+
+[MIT](LICENSE)

package/bin/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+const childProcess = require('child_process');
+
+const goos = process.platform === 'win32' ? 'windows' : process.platform;
+const goarch = process.arch === 'x64' ? 'amd64' : process.arch;
+const suffix = process.platform === 'win32' ? '.exe' : '';
+const packageName = `@futuretea/clickhouse-mcp-server-${goos}-${goarch}`;
+
+let binaryPath;
+try {
+  binaryPath = require.resolve(`${packageName}/bin/clickhouse-mcp-server${suffix}`);
+} catch {
+  throw new Error(`Could not resolve binary path for platform/architecture: ${process.platform}/${process.arch}`);
+}
+
+const child = childProcess.spawn(binaryPath, ['mcp', ...process.argv.slice(2)], {
+  stdio: 'inherit',
+});
+
+for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) {
+  process.on(signal, () => {
+    if (!child.killed) child.kill(signal);
+  });
+}
+
+child.on('close', (code, signal) => {
+  if (signal) process.exit(128 + (signal === 'SIGTERM' ? 15 : signal === 'SIGINT' ? 2 : 1));
+  process.exit(code || 0);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@futuretea/clickhouse-mcp-server",
+  "version": "0.0.1",
+  "description": "Read-only ClickHouse Model Context Protocol server",
+  "main": "./bin/index.js",
+  "bin": {
+    "clickhouse-mcp-server": "bin/index.js"
+  },
+  "optionalDependencies": {
+    "@futuretea/clickhouse-mcp-server-darwin-amd64": "0.0.1",
+    "@futuretea/clickhouse-mcp-server-darwin-arm64": "0.0.1",
+    "@futuretea/clickhouse-mcp-server-linux-amd64": "0.0.1",
+    "@futuretea/clickhouse-mcp-server-linux-arm64": "0.0.1",
+    "@futuretea/clickhouse-mcp-server-windows-amd64": "0.0.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/futuretea/clickhouse-mcp-server.git"
+  },
+  "keywords": [
+    "mcp",
+    "clickhouse",
+    "database",
+    "model-context-protocol"
+  ],
+  "author": {
+    "name": "futuretea",
+    "url": "https://github.com/futuretea"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/futuretea/clickhouse-mcp-server/issues"
+  },
+  "homepage": "https://github.com/futuretea/clickhouse-mcp-server#readme"
+}