{"id":30874444,"url":"https://github.com/altinity/altinity-mcp","last_synced_at":"2025-09-08T00:48:05.299Z","repository":{"id":301904353,"uuid":"997237002","full_name":"Altinity/altinity-mcp","owner":"Altinity","description":"Model Context Protocol server to use ClickHouse®  databases in your AI agents","archived":false,"fork":false,"pushed_at":"2025-09-04T02:46:05.000Z","size":1537,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-04T04:39:10.691Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Altinity.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-06T07:25:05.000Z","updated_at":"2025-09-04T02:46:09.000Z","dependencies_parsed_at":"2025-07-28T20:17:26.777Z","dependency_job_id":"4633f47d-47f6-4af8-8f82-0be1508afcdf","html_url":"https://github.com/Altinity/altinity-mcp","commit_stats":null,"previous_names":["altinity/altinity-mcp"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/Altinity/altinity-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Altinity%2Faltinity-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Altinity%2Faltinity-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Altinity%2Faltinity-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Altinity%2Faltinity-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Altinity","download_url":"https://codeload.github.com/Altinity/altinity-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Altinity%2Faltinity-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274117523,"owners_count":25225104,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-08T00:47:45.606Z","updated_at":"2025-09-08T00:48:05.281Z","avatar_url":"https://github.com/Altinity.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Altinity MCP Server\n\n[![Coverage Status](https://coveralls.io/repos/github/Altinity/altinity-mcp/badge.svg)](https://coveralls.io/github/Altinity/altinity-mcp)\n\nA Model Context Protocol (MCP) server that provides tools for interacting with ClickHouse® databases. This server enables AI assistants and other MCP clients to query, analyze, and interact with ClickHouse® databases through a standardized protocol.\n\n## Features\n\n- **Multiple Transport Options**: Support for STDIO, HTTP, and Server-Sent Events (SSE) transports\n- **JWE Authentication**: Optional JWE-based authentication with encryption for secure database access\n- **TLS Support**: Full TLS encryption support for both ClickHouse® connections and MCP server endpoints\n- **Comprehensive Tools**: Built-in tools for listing tables, describing schemas, and executing queries\n- **Resource Templates**: Dynamic resource discovery for database schemas and table information\n- **Query Prompts**: AI-assisted query building and optimization prompts\n- **Configuration Management**: Flexible configuration via files, environment variables, or CLI flags\n- **Hot Reload**: Dynamic configuration reloading without server restart\n\n## Table of Contents\n- [Quick Start](#quick-start)\n- [Integration Guide](#integration-guide)\n- [Installation \u0026 Deployment](#installation--deployment)\n- [Configuration](#configuration)\n- [Available Tools](#available-tools)\n- [Available Resources](#available-resources)\n- [Available Prompts](#available-prompts)\n- [OpenAI GPTs Integration](#openai-gpts-integration)\n- [JWE Authentication](#jwe-authentication)\n- [TLS Configuration](#tls-configuration)\n- [Testing](#testing)\n- [Development](#development)\n- [CLI Reference](#cli-reference)\n- [Contributing](#contributing)\n- [License](#license)\n- [Support](#support)\n\n## Quick Start\n\n### Using STDIO Transport (Default)\n\n```bash\n# Basic usage with default settings\n./altinity-mcp --clickhouse-host localhost --clickhouse-port 8123\n\n# With custom database and credentials\n./altinity-mcp \\\n  --clickhouse-host clickhouse.example.com \\\n  --clickhouse-port 9000 \\\n  --clickhouse-protocol tcp \\\n  --clickhouse-database analytics \\\n  --clickhouse-username reader \\\n  --clickhouse-password secret123 \\\n  --clickhouse-limit 5000\n```\n\n### Using HTTP Transport with OpenAPI\n\n```bash\n./altinity-mcp \\\n  --transport http \\\n  --address 0.0.0.0 \\\n  --port 8080 \\\n  --clickhouse-host localhost \\\n  --openapi http\n```\n\n### Using SSE Transport with JWE Authentication and OpenAPI\n\n```bash\n./altinity-mcp \\\n  --transport sse \\\n  --port 8080 \\\n  --allow-jwe-auth \\\n  --jwe-secret-key \"your-jwe-encryption-secret\" \\\n  --jwt-secret-key \"your-jwt-signing-secret\" \\\n  --clickhouse-host localhost \\\n  --openapi http\n```\n\n## Integration Guide\n\nFor detailed instructions on integrating Altinity MCP with various AI tools and platforms, see our [Integration Guide](docs/howto_integrate.md).\n\n## Installation \u0026 Deployment\n\n### Using Docker\n\n```bash\ndocker run -it altinity/altinity-mcp:latest --clickhouse-host clickhouse\n```\n\n### Kubernetes with Helm\n\nFrom OCI helm registry (recommended)\n```bash\n# Install from OCI registry\nhelm install altinity-mcp oci://ghcr.io/altinity/altinity-mcp/helm/altinity-mcp \\\n  --set config.clickhouse.host=clickhouse.example.com \\\n  --set config.clickhouse.database=default \\\n  --set config.clickhouse.limit=5000\n```\n\nFrom local helm chart\n```bash\ngit clone https://github.com/Altinity/altinity-mcp\ncd altinity-mcp\nhelm install altinity-mcp ./helm/altinity-mcp \\\n  --set config.clickhouse.host=clickhouse-service \\\n  --set config.clickhouse.database=analytics \\\n  --set config.server.transport=http \\\n  --set config.server.port=8080\n```\n\nFor detailed Helm chart configuration options, see [Helm Chart README](helm/altinity-mcp/README.md).\n\n### Docker Compose\n\n```yaml\nversion: '3.8'\nservices:\n  altinity-mcp:\n    build: .\n    ports:\n      - \"8080:8080\"\n    environment:\n      - CLICKHOUSE_HOST=clickhouse\n      - MCP_TRANSPORT=http\n      - MCP_PORT=8080\n    depends_on:\n      - clickhouse\n    entrypoint: [\"/bin/sh\", \"-c\", \"/bin/altinity-mcp\"]\n  \n  clickhouse:\n    image: clickhouse/clickhouse-server:latest\n    ports:\n      - \"8123:8123\"\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/altinity/altinity-mcp.git\ncd altinity-mcp\ngo build -o altinity-mcp ./cmd/altinity-mcp\n```\n\n\n## Configuration\n\n### Configuration File\n\nCreate a YAML or JSON configuration file:\n\n```yaml\n# config.yaml\nclickhouse:\n  host: \"localhost\"\n  port: 8123\n  database: \"default\"\n  username: \"default\"\n  password: \"\"\n  protocol: \"http\"\n  read_only: false\n  max_execution_time: 600\n  tls:\n    enabled: false\n    ca_cert: \"\"\n    client_cert: \"\"\n    client_key: \"\"\n    insecure_skip_verify: false\n\nserver:\n  transport: \"stdio\"\n  address: \"0.0.0.0\"\n  port: 8080\n  tls:\n    enabled: false\n    cert_file: \"\"\n    key_file: \"\"\n    ca_cert: \"\"\n  jwt:\n    enabled: false\n    secret_key: \"\"\n  openapi:\n    enabled: false\n    tls: false\n\nlogging:\n  level: \"info\"\n```\n\nUse the configuration file:\n\n```bash\n./altinity-mcp --config config.yaml\n```\n\n### Environment Variables\n\nAll configuration options can be set via environment variables:\n\n```bash\nexport CLICKHOUSE_HOST=localhost\nexport CLICKHOUSE_PORT=8123\nexport CLICKHOUSE_DATABASE=analytics\nexport CLICKHOUSE_LIMIT=5000\nexport MCP_TRANSPORT=http\nexport MCP_PORT=8080\nexport LOG_LEVEL=debug\n\n./altinity-mcp\n```\n\n## Available Tools\n\n### `list_tables`\nLists all tables in a ClickHouse® database with detailed information.\n\n**Parameters:**\n- `database` (optional): The database to list tables from\n\n### `describe_table`\nDescribes the schema of a specific table including column types, constraints, and metadata.\n\n**Parameters:**\n- `database` (required): The database name\n- `table_name` (required): The table name\n\n### `execute_query`\nExecutes SQL queries against ClickHouse® with optional result limiting.\n\n**Parameters:**\n- `query` (required): The SQL query to execute\n- `limit` (optional): Maximum number of rows to return (default: server configured limit, max: 10,000)\n\n## Available Resources\n\n### `clickhouse://schema`\nProvides complete schema information for the ClickHouse® database in JSON format.\n\n### `clickhouse://table/{database}/{table}`\nProvides detailed information about a specific table including schema, sample data, and statistics.\n\n## Available Prompts\n\n### `query_builder`\nHelps build efficient ClickHouse® SQL queries with context about available tables and best practices.\n\n**Arguments:**\n- `database` (required): Name of the database\n- `table_name` (optional): Specific table to focus on\n- `query_type` (optional): Type of query (SELECT, INSERT, etc.)\n\n## OpenAI GPTs Integration\n\nThe Altinity MCP Server supports seamless integration with OpenAI GPTs through its OpenAPI-compatible endpoints. These endpoints enable GPT assistants to perform ClickHouse® database operations directly.\n\n### Authentication\n- **With JWE**: Add the JWE token to either:\n  1. Path parameter: `/{jwe_token}/openapi/...` (now required)\n  2. Authorization header: `Bearer {token}` (alternative)\n  3. `x-altinity-mcp-key` header (alternative)\n- **Without JWE**: Use server-configured credentials (no auth needed in requests)\n\n### Available Actions\n\n#### 1. List Tables in Database\n**Path**: `/openapi/list_tables`  \n**Parameters**:\n- `jwe_token` (path param): JWE authentication token\n- `database` (query param): Name of database (optional, returns all databases if omitted)\n\n**Example OpenAPI Path**:\n```\nGET /{jwe_token}/openapi/list_tables?database={db_name}\n```\n\n#### 2. Describe Table Structure\n**Path**: `/openapi/describe_table`  \n**Parameters**:\n- `jwe_token` (path param): JWE authentication token\n- `database` (query param): Name of database (required)\n- `table_name` (query param): Name of table to describe (required)\n\n**Example OpenAPI Path**:\n```\nGET /{jwe_token}/openapi/describe_table?database={db_name}\u0026table_name={table_name}\n```\n\n#### 3. Execute SQL Query\n**Path**: `/openapi/execute_query`  \n**Parameters**:\n- `jwe_token` (path param): JWE authentication token\n- `query` (query param): SQL query to execute (required)\n- `limit` (query param): Maximum rows to return (optional, default 1000, max 10000)\n\n**Example OpenAPI Path**:\n```\nGET /{jwe_token}/openapi/execute_query?query=SELECT%20*%20FROM%20table\u0026limit=500\n```\n\n### Configuration Example for GPTs\n```json\n{\n  \"openapi\": \"3.1.0\",\n  \"info\": {\n    \"title\": \"ClickHouse® SQL Interface\",\n    \"version\": \"1.0.0\"\n  },\n  \"servers\": [\n    {\"url\": \"https://your-server:8080/{token}\"}\n  ],\n  \"paths\": {\n    \"/{jwe_token}/openapi/list_tables\": {\n      \"get\": {\n        \"operationId\": \"list_tables\",\n        \"parameters\": [\n          {\n            \"name\": \"jwe_token\",\n            \"in\": \"path\",\n            \"required\": true,\n            \"schema\": {\"type\": \"string\"}\n          },\n          {\n            \"name\": \"database\",\n            \"in\": \"query\",\n            \"schema\": {\"type\": \"string\"}\n          }\n        ]\n      }\n    },\n    \"/{jwe_token}/openapi/describe_table\": {\n      \"get\": {\n        \"operationId\": \"describe_table\",\n        \"parameters\": [\n          {\n            \"name\": \"jwe_token\",\n            \"in\": \"path\",\n            \"required\": true,\n            \"schema\": {\"type\": \"string\"}\n          },\n          {\n            \"name\": \"database\",\n            \"in\": \"query\",\n            \"required\": true\n          },\n          {\n            \"name\": \"table_name\",\n            \"in\": \"query\",\n            \"required\": true\n          }\n        ]\n      }\n    },\n    \"/{jwe_token}/openapi/execute_query\": {\n      \"get\": {\n        \"operationId\": \"execute_query\",\n        \"parameters\": [\n          {\n            \"name\": \"jwe_token\",\n            \"in\": \"path\",\n            \"required\": true,\n            \"schema\": {\"type\": \"string\"}\n          },\n          {\n            \"name\": \"query\",\n            \"in\": \"query\",\n            \"required\": true\n          },\n          {\n            \"name\": \"limit\",\n            \"in\": \"query\",\n            \"schema\": {\"type\": \"integer\"}\n          }\n        ]\n      }\n    }\n  }\n}\n```\n\n\u003e **Note**: For Altinity Cloud deployments, use the provided endpoint URL with your organization-specific token.\n\n## JWE Authentication\n\nWhen JWE authentication is enabled, the server expects tokens encrypted using AES Key Wrap (A256KW) and AES-GCM (A256GCM). These tokens contain ClickHouse® connection parameters:\n\n```json\n{\n  \"host\": \"clickhouse.example.com\",\n  \"port\": 8123,\n  \"database\": \"analytics\",\n  \"username\": \"user123\",\n  \"password\": \"secret\",\n  \"protocol\": \"http\",\n  \"secure\": \"false\"\n}\n```\n\nGenerate tokens using the provided utility. \n\n```bash\ngo run ./cmd/jwe_auth/jwe_token_generator.go \\\n  --jwe-secret-key \"your-jwe-encryption-secret\" \\\n  --jwt-secret-key \"your-jwt-signing-secret\" \\\n  --host \"clickhouse.example.com\" \\\n  --port 8123 \\\n  --database \"analytics\" \\\n  --username \"user123\" \\\n  --password \"password123\" \\\n  --expiry 86400\n```\nMore details in [jwe_authentication.md](docs/jwe_authentication.md)\n\n## TLS Configuration\n\n### ClickHouse® TLS\n\n```bash\n./altinity-mcp \\\n  --clickhouse-tls \\\n  --clickhouse-tls-ca-cert /path/to/ca.crt \\\n  --clickhouse-tls-client-cert /path/to/client.crt \\\n  --clickhouse-tls-client-key /path/to/client.key\n```\n\n### Server TLS\n\n```bash\n./altinity-mcp \\\n  --transport https \\\n  --server-tls \\\n  --server-tls-cert-file /path/to/server.crt \\\n  --server-tls-key-file /path/to/server.key\n```\n\n## Testing\n\n### Test ClickHouse® Connection\n\n```bash\n./altinity-mcp test-connection \\\n  --clickhouse-host localhost \\\n  --clickhouse-port 8123 \\\n  --clickhouse-database default\n```\n\n### Run Tests\n\n```bash\ngo test ./...\n```\n\n### Integration Tests\n\nIntegration tests use Docker containers and require Docker to be running:\n\n```bash\ngo test -v ./cmd/altinity-mcp/...\n```\n\n## Development\n\n### Prerequisites\n\n- Go 1.24 or later\n- Docker (for integration tests)\n- ClickHouse® server (for development)\n\n### Building\n\n```bash\ngo build -o altinity-mcp ./cmd/altinity-mcp\n```\n\n### Running Tests\n\n```bash\n# Unit tests\ngo test ./pkg/...\n\n# Integration tests (requires Docker)\ngo test -v ./cmd/altinity-mcp/...\n```\n\n## CLI Reference\n\n### Global Flags\n\n- `--config`: Path to configuration file (YAML or JSON)\n- `--log-level`: Logging level (debug/info/warn/error)\n- `--clickhouse-limit`: Default limit for query results (default: 1000)\n- `--openapi`: Enable OpenAPI endpoints (disable/http/https) (default: disable)\n\n### ClickHouse® Flags\n\n- `--clickhouse-host`: ClickHouse® server host\n- `--clickhouse-port`: ClickHouse® server port\n- `--clickhouse-database`: Database name\n- `--clickhouse-username`: Username\n- `--clickhouse-password`: Password\n- `--clickhouse-protocol`: Protocol (http/tcp)\n- `--read-only`: Read-only mode\n- `--clickhouse-max-execution-time`: Query timeout in seconds\n\n### Server Flags\n\n- `--transport`: Transport type (stdio/http/sse)\n- `--address`: Server address\n- `--port`: Server port\n- `--allow-jwe-auth`: Enable JWE authentication\n- `--jwe-secret-key`: Secret key for JWE token decryption (must be 32 bytes for A256KW).\n- `--jwt-secret-key`: Secret key for JWT signature verification\n\n### Commands\n\n- `version`: Show version information\n- `test-connection`: Test ClickHouse® connection\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Run the test suite\n6. Submit a pull request\n\n## License\n\nThis project is licensed under the Apache License 2.0. See the LICENSE file for details.\n\n## Support\n\nFor support and questions:\n- GitHub Issues: [https://github.com/altinity/altinity-mcp/issues](https://github.com/altinity/altinity-mcp/issues)\n- Email: support@altinity.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faltinity%2Faltinity-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faltinity%2Faltinity-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faltinity%2Faltinity-mcp/lists"}