{"_id":"@arvoretech/clickhouse-mcp","_rev":"6-ed3606c6f252743d262d6c847bea8ffc","name":"@arvoretech/clickhouse-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@arvoretech/clickhouse-mcp","version":"1.0.0","keywords":["mcp","clickhouse","database","olap","analytics","llm","ai","arvore"],"author":{"name":"Arvore"},"license":"MIT","_id":"@arvoretech/clickhouse-mcp@1.0.0","maintainers":[{"name":"joao.barros.arvore","email":"joao.barros@arvore.com.br"}],"homepage":"https://github.com/arvoreeducacao/arvore-mcp-servers#readme","bugs":{"url":"https://github.com/arvoreeducacao/arvore-mcp-servers/issues"},"bin":{"clickhouse-mcp":"dist/index.js"},"dist":{"shasum":"670670507e6c5bd9b059490298f8e46acd417c96","tarball":"https://registry.npmjs.org/@arvoretech/clickhouse-mcp/-/clickhouse-mcp-1.0.0.tgz","fileCount":30,"integrity":"sha512-U0h01hcKccUl8VEsF55jvAdSMUb2W9+eU64n9IR9KaUO4t09HmRvudIGMHGQJ64Z8awTyubiKbJfVsG2GPtP7Q==","signatures":[{"sig":"MEUCIQC6zmEnTDDlDA5Fxjbrp0uJZxgHntU/709EVSULExnyrAIgPsWbhiFYjsfZcjyazZD5yuA9zKT3P+CHKUBVbHt/INM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":57246},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"a100e893c94e0aaba5ca776ae0690cd801b3dc37","scripts":{"dev":"tsx src/index.ts","lint":"eslint src/**/*.ts","test":"vitest","build":"tsc","start":"node dist/index.js","lint:fix":"eslint src/**/*.ts --fix","test:cov":"vitest --coverage"},"_npmUser":{"name":"joao.barros.arvore","email":"joao.barros@arvore.com.br"},"repository":{"url":"git+https://github.com/arvoreeducacao/arvore-mcp-servers.git","type":"git","directory":"packages/clickhouse"},"_npmVersion":"10.8.2","description":"ClickHouse MCP Server for read-only database operations","directories":{},"_nodeVersion":"20.20.0","dependencies":{"zod":"^3.22.4","@clickhouse/client":"^1.8.1","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/clickhouse-mcp_1.0.0_1772909275919_0.3941032790883454","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-03-07T18:47:55.815Z","modified":"2026-06-16T21:13:10.954Z","1.0.0":"2026-03-07T18:47:56.072Z"},"bugs":{"url":"https://github.com/arvoreeducacao/arvore-mcp-servers/issues"},"author":{"name":"Arvore"},"license":"MIT","homepage":"https://github.com/arvoreeducacao/arvore-mcp-servers#readme","keywords":["mcp","clickhouse","database","olap","analytics","llm","ai","arvore"],"repository":{"url":"git+https://github.com/arvoreeducacao/arvore-mcp-servers.git","type":"git","directory":"packages/clickhouse"},"description":"ClickHouse MCP Server for read-only database operations","maintainers":[{"email":"joao.barros@arvore.com.br","name":"joao.barros.arvore"},{"email":"rafasouza@protonmail.com","name":"rafsouza"},{"email":"pedro.adas@gmail.com","name":"pedro.adas"},{"email":"guilhermebscontact@gmail.com","name":"guilhermebs"},{"email":"ricardorbxx1@gmail.com","name":"ricardoraposorfox"},{"email":"jvgcunha2002@gmail.com","name":"jott4"},{"email":"vitor.piovezan@arvore.com.br","name":"vitor.piovezan"}],"readme":"# ClickHouse MCP Server\n\nA Model Context Protocol (MCP) server implementation for ClickHouse that enables read-only database operations through a standardized protocol for integration with LLMs and AI tools.\n\n## Why not the official ClickHouse MCP?\n\nThe official ClickHouse MCP server requires OAuth re-authentication frequently, which breaks long agent sessions. Complex or heavy queries often hit timeout limits and fail silently. This server connects directly via `@clickhouse/client` with static credentials, so there's no auth interruption and you get full control over request timeouts.\n\n## Features\n\n- **Read-only**: Executes only SELECT, SHOW, DESCRIBE, EXPLAIN and WITH (CTE) queries\n- **Secure**: Validates queries to prevent write operations\n- **No OAuth**: Direct connection with static credentials — no re-authentication needed\n- **Configurable timeout**: Handles complex/heavy queries without premature timeouts\n- **Fast**: Direct ClickHouse connection using @clickhouse/client\n- **MCP Protocol**: Communication via stdio transport\n- **TypeScript**: Fully typed with Zod validation\n- **Environment Configuration**: Easy setup via environment variables\n\n## Installation\n\n```bash\nnpm install -g @arvoretech/clickhouse-mcp\n```\n\n## Configuration\n\nThe server is configured via environment variables:\n\n```bash\nexport CLICKHOUSE_URL=http://localhost:8123\nexport CLICKHOUSE_USER=default\nexport CLICKHOUSE_PASSWORD=secret\nexport CLICKHOUSE_DATABASE=default\nexport CLICKHOUSE_REQUEST_TIMEOUT=30000\n```\n\n## Usage\n\n```bash\n# Development\npnpm dev\n\n# Production\nnode dist/index.js\n```\n\n## Available MCP Tools\n\n### `read_query`\n\nExecutes read-only SQL queries on the ClickHouse database.\n\n**Parameters:**\n\n- `query` (string): SQL SELECT statement\n\n### `list_tables`\n\nLists all tables in the specified database.\n\n**Parameters:**\n\n- `database` (string, optional): Database name (defaults to configured database)\n\n### `describe_table`\n\nGets column structure of a specific table including types, keys, and defaults.\n\n**Parameters:**\n\n- `tableName` (string): Name of the table\n- `database` (string, optional): Database name\n\n### `list_databases`\n\nLists all available databases on the ClickHouse server.\n\n**Parameters:** None\n\n## Programmatic Usage\n\n```typescript\nimport { ClickHouseMCPServer } from \"@arvoretech/clickhouse-mcp\";\n\nconst server = new ClickHouseMCPServer({\n  url: \"https://your-host:8443\",\n  username: \"default\",\n  password: \"secret\",\n  database: \"default\",\n  requestTimeout: 30000,\n});\n\nserver.setupGracefulShutdown();\nawait server.start();\n```\n\n## Claude Desktop Integration\n\n```json\n{\n  \"mcpServers\": {\n    \"clickhouse\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@arvoretech/clickhouse-mcp\"],\n      \"env\": {\n        \"CLICKHOUSE_URL\": \"https://your-host:8443\",\n        \"CLICKHOUSE_USER\": \"default\",\n        \"CLICKHOUSE_PASSWORD\": \"secret\",\n        \"CLICKHOUSE_DATABASE\": \"default\"\n      }\n    }\n  }\n}\n```\n\n## Development\n\n```bash\npnpm install\npnpm dev\npnpm build\npnpm test\npnpm lint\n```\n\n## Limitations\n\n- Read-only operations only (SELECT, SHOW, DESCRIBE, EXPLAIN, WITH)\n- ClickHouse only\n- Stdio transport only (no HTTP/WebSocket)\n","readmeFilename":"README.md"}