{"id":46156956,"url":"https://github.com/likidu/mcp-server-tidbcloud","last_synced_at":"2026-03-02T10:13:10.542Z","repository":{"id":335142721,"uuid":"1143598828","full_name":"likidu/mcp-server-tidbcloud","owner":"likidu","description":"MCP server for interacting with TiDB Cloud OpenAPI and databases","archived":false,"fork":false,"pushed_at":"2026-02-18T01:40:41.000Z","size":484,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-18T06:52:26.060Z","etag":null,"topics":["database","mcp","mcp-server"],"latest_commit_sha":null,"homepage":"https://tidb.link/mcp","language":"TypeScript","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/likidu.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2026-01-27T19:24:08.000Z","updated_at":"2026-02-18T01:41:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/likidu/mcp-server-tidbcloud","commit_stats":null,"previous_names":["likidu/mcp-server-tidbcloud"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/likidu/mcp-server-tidbcloud","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/likidu%2Fmcp-server-tidbcloud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/likidu%2Fmcp-server-tidbcloud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/likidu%2Fmcp-server-tidbcloud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/likidu%2Fmcp-server-tidbcloud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/likidu","download_url":"https://codeload.github.com/likidu/mcp-server-tidbcloud/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/likidu%2Fmcp-server-tidbcloud/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29998487,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T09:59:02.300Z","status":"ssl_error","status_checked_at":"2026-03-02T09:59:02.001Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["database","mcp","mcp-server"],"created_at":"2026-03-02T10:13:09.122Z","updated_at":"2026-03-02T10:13:10.534Z","avatar_url":"https://github.com/likidu.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TiDB Cloud MCP Server\n\nAn MCP (Model Context Protocol) server that enables LLMs to interact with TiDB Cloud through natural language.\n\n## Features\n\n- **Cluster Management**: Create, list, update, and delete TiDB Cloud Serverless clusters\n- **Branch Management**: Create, list, get, and delete branches for clusters\n- **Database Operations**: Execute SQL queries and manage database schemas\n- **Region Discovery**: List available regions for cluster creation\n- **Async Operation Support**: Proper handling of long-running operations with status checking\n- **Two Transport Options**:\n  - **stdio**: Local server for Claude Desktop (API keys in env vars)\n  - **Streamable HTTP**: Remote server for hosted deployments (API keys in headers)\n\n## Prerequisites\n\n- Node.js 22 or later\n- pnpm package manager\n- TiDB Cloud account with API access\n\n## Getting Your API Keys\n\n1. Log in to [TiDB Cloud Console](https://tidbcloud.com)\n2. Click on your organization name in the left sidebar\n3. Navigate to **Organization Settings** → **API Keys**\n4. Click **Create API Key**\n5. Copy both the **Public Key** and **Private Key** (save the private key securely - it won't be shown again)\n\n## Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/tidbcloud/mcp-server-tidbcloud.git\ncd mcp-server-tidbcloud\n\n# Install dependencies\npnpm install\n\n# Build the project\npnpm build\n```\n\n## Usage with Claude Desktop\n\nThere are two ways to use this MCP server with Claude Desktop:\n\n### Option 1: Local Server (stdio) — Recommended\n\nRun the server locally with API keys configured in Claude Desktop. Best for development or when you need full control.\n\nAdd the following to your Claude Desktop configuration file (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"tidbcloud\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mcp-server-tidbcloud/packages/server/dist/index.js\"],\n      \"env\": {\n        \"TIDB_CLOUD_PUBLIC_KEY\": \"your-public-key\",\n        \"TIDB_CLOUD_PRIVATE_KEY\": \"your-private-key\"\n      }\n    }\n  }\n}\n```\n\n**Environment Variables (Local Server):**\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `TIDB_CLOUD_PUBLIC_KEY` | Yes | TiDB Cloud API public key |\n| `TIDB_CLOUD_PRIVATE_KEY` | Yes | TiDB Cloud API private key |\n| `TIDB_CLOUD_API_URL` | No | API base URL (defaults to `https://serverless.tidbapi.com`) |\n| `TIDB_CLOUD_DB_HOST` | No | Default database host for SQL operations |\n| `TIDB_CLOUD_DB_USER` | No | Default database username |\n| `TIDB_CLOUD_DB_PASSWORD` | No | Default database password |\n\n### Option 2: Remote Server\n\nConnect to the hosted MCP server using `mcp-remote`. Your API keys are passed via headers — they are not stored on the server.\n\n**Claude Desktop Configuration:**\n\n```json\n{\n  \"mcpServers\": {\n    \"TiDB Cloud\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\", \"mcp-remote\",\n        \"https://mcp-server-tidbcloud.workers.dev/mcp\",\n        \"--header\", \"X-TiDB-API-Public-Key:${TIDB_CLOUD_PUBLIC_KEY}\",\n        \"--header\", \"X-TiDB-API-Private-Key:${TIDB_CLOUD_PRIVATE_KEY}\"\n      ],\n      \"env\": {\n        \"TIDB_CLOUD_PUBLIC_KEY\": \"your-public-key\",\n        \"TIDB_CLOUD_PRIVATE_KEY\": \"your-private-key\"\n      }\n    }\n  }\n}\n```\n\n**With Database Credentials (for SQL operations):**\n\nTo use database tools (`show_databases`, `db_query`, `db_execute`, etc.), configure your database credentials. The credentials are stored locally and sent via custom headers:\n\n```json\n{\n  \"mcpServers\": {\n    \"TiDB Cloud\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\", \"mcp-remote\",\n        \"https://mcp-server-tidbcloud.workers.dev/mcp\",\n        \"--header\", \"X-TiDB-API-Public-Key:${TIDB_CLOUD_PUBLIC_KEY}\",\n        \"--header\", \"X-TiDB-API-Private-Key:${TIDB_CLOUD_PRIVATE_KEY}\",\n        \"--header\", \"X-TiDB-DB-Host:${TIDB_CLOUD_DB_HOST}\",\n        \"--header\", \"X-TiDB-DB-User:${TIDB_CLOUD_DB_USER}\",\n        \"--header\", \"X-TiDB-DB-Password:${TIDB_CLOUD_DB_PASSWORD}\"\n      ],\n      \"env\": {\n        \"TIDB_CLOUD_PUBLIC_KEY\": \"your-public-key\",\n        \"TIDB_CLOUD_PRIVATE_KEY\": \"your-private-key\",\n        \"TIDB_CLOUD_DB_HOST\": \"gateway01.us-east-1.prod.aws.tidbcloud.com\",\n        \"TIDB_CLOUD_DB_USER\": \"your-username\",\n        \"TIDB_CLOUD_DB_PASSWORD\": \"your-password\"\n      }\n    }\n  }\n}\n```\n\nTo get your cluster's host, use the `tidbcloud_get_cluster` tool - it will display the connection endpoint. Your username format is typically `{userPrefix}.root` where `userPrefix` is shown in the cluster details.\n\n## Available Tools\n\n### Region Tools\n\n#### `tidbcloud_list_regions`\n\nLists all available regions for TiDB Cloud Serverless clusters.\n\n**Parameters:** None\n\n### Cluster Management\n\n#### `tidbcloud_list_clusters`\n\nLists all TiDB Cloud Serverless clusters in your organization.\n\n**Parameters:**\n- `pageSize` (optional): Number of clusters per page (1-100, default 10)\n- `pageToken` (optional): Token for fetching the next page\n\n#### `tidbcloud_get_cluster`\n\nGets detailed information about a specific cluster, including connection endpoint (host and port).\n\n**Parameters:**\n- `cluster` (required): The cluster name or ID\n\n#### `tidbcloud_create_cluster`\n\nCreates a new TiDB Cloud Serverless cluster. This is an async operation - the cluster will be in CREATING state initially.\n\n**Parameters:**\n- `displayName` (required): Display name for the cluster (max 64 chars)\n- `region` (required): Cloud region name (use `tidbcloud_list_regions` to get valid values)\n- `rootPassword` (optional): Root password. Auto-generated if not provided\n- `spendingLimitMonthly` (optional): Monthly spending limit in USD\n- `labels` (optional): Key-value labels for the cluster\n\n#### `tidbcloud_update_cluster`\n\nUpdates an existing cluster's configuration.\n\n**Parameters:**\n- `cluster` (required): The cluster name or ID to update\n- `displayName` (optional): New display name\n- `spendingLimitMonthly` (optional): Monthly spending limit in USD\n- `labels` (optional): Key-value labels\n\n#### `tidbcloud_delete_cluster`\n\nDeletes a cluster. **Warning: This is irreversible!**\n\n**Parameters:**\n- `cluster` (required): The cluster name or ID to delete\n\n### Branch Management\n\n#### `tidbcloud_list_branches`\n\nLists all branches for a cluster.\n\n**Parameters:**\n- `cluster` (required): The cluster name or ID\n- `pageSize` (optional): Number of branches per page (1-100)\n- `pageToken` (optional): Token for pagination\n\n#### `tidbcloud_get_branch`\n\nGets detailed information about a specific branch, including connection endpoint. Useful for checking if a branch has finished creating.\n\n**Parameters:**\n- `cluster` (required): The cluster name or ID\n- `branch` (required): The branch name or ID\n\n#### `tidbcloud_create_branch`\n\nCreates a new branch for a TiDB Cloud Starter or Essential cluster. This is an async operation.\n\n**Parameters:**\n- `cluster` (required): The cluster name or ID\n- `displayName` (required): Display name for the new branch (max 64 characters)\n- `parentId` (optional): Parent branch ID (defaults to main cluster)\n- `parentTimestamp` (optional): RFC3339 timestamp for point-in-time branching\n\n#### `tidbcloud_delete_branch`\n\nDeletes a branch. **Warning: This is irreversible!**\n\n**Parameters:**\n- `cluster` (required): The cluster name or ID\n- `branch` (required): The branch name or ID to delete\n\n### Database Operations\n\nDatabase tools require connection credentials. Set them via environment variables or pass them as parameters.\n\n#### `show_databases`\n\nLists all databases in the TiDB Cloud cluster.\n\n**Parameters:**\n- `host` (optional): Database host override\n- `username` (optional): Username override\n- `password` (optional): Password override\n\n#### `show_tables`\n\nLists all tables in a specified database.\n\n**Parameters:**\n- `database` (required): The database to list tables from\n- `host` (optional): Database host override\n- `username` (optional): Username override\n- `password` (optional): Password override\n\n#### `db_query`\n\nExecutes a read-only SQL query. Only SELECT, SHOW, DESCRIBE, and EXPLAIN statements are allowed.\n\n**Parameters:**\n- `sql` (required): The read-only SQL query to execute\n- `database` (optional): Database to use for the query\n- `host` (optional): Database host override\n- `username` (optional): Username override\n- `password` (optional): Password override\n\n#### `db_execute`\n\nExecutes SQL statements that modify data or schema (INSERT, UPDATE, DELETE, CREATE, ALTER, DROP). **Warning: This can modify or delete data.**\n\n**Parameters:**\n- `sql` (required): SQL statement or array of statements to execute\n- `database` (optional): Database to use\n- `host` (optional): Database host override\n- `username` (optional): Username override\n- `password` (optional): Password override\n\n#### `db_create_user`\n\nCreates a new database user.\n\n**Parameters:**\n- `username` (required): Username for the new user\n- `password` (required): Password for the new user\n- `userHost` (optional): Host restriction (default: '%' for any host)\n- `host` (optional): Admin database host override\n- `adminUsername` (optional): Admin username override\n- `adminPassword` (optional): Admin password override\n\n#### `db_remove_user`\n\nRemoves a database user. **Warning: This is irreversible!**\n\n**Parameters:**\n- `username` (required): Username of the user to remove\n- `userHost` (optional): Host specification (default: '%')\n- `host` (optional): Admin database host override\n- `adminUsername` (optional): Admin username override\n- `adminPassword` (optional): Admin password override\n\n## Async Operations\n\nSome operations (cluster creation, branch creation, deletions) are asynchronous. The tools will return immediately with the current state, and you can use the corresponding `get` tool to check when the operation completes:\n\n- After `tidbcloud_create_cluster`: Use `tidbcloud_get_cluster` to check when state changes from `CREATING` to `ACTIVE`\n- After `tidbcloud_create_branch`: Use `tidbcloud_get_branch` to check when state changes from `CREATING` to `ACTIVE`\n\n## Development\n\n```bash\n# Run in development mode with auto-reload\npnpm dev\n\n# Build the project\npnpm build\n\n# Clean build artifacts\npnpm clean\n\n# Test with MCP Inspector (stdio server)\nTIDB_CLOUD_PUBLIC_KEY='your-key' TIDB_CLOUD_PRIVATE_KEY='your-key' \\\n  npx @modelcontextprotocol/inspector node packages/server/dist/index.js\n```\n\n### Test Remote Server with MCP Inspector\n\nTo test the remote HTTP server locally with API key authentication:\n\n1. Start the remote server:\n```bash\npnpm dev:remote\n```\n\n2. In a separate terminal, connect the MCP inspector via `mcp-remote` with API key headers:\n```bash\nnpx @modelcontextprotocol/inspector \\\n  npx mcp-remote http://localhost:3000/mcp \\\n  --header \"X-TiDB-API-Public-Key:YOUR_PUBLIC_KEY\" \\\n  --header \"X-TiDB-API-Private-Key:YOUR_PRIVATE_KEY\"\n```\n\n## Project Structure\n\n```\nmcp-server-tidbcloud/\n├── packages/\n│   ├── server/                    # Core MCP Server (stdio transport)\n│   │   ├── src/\n│   │   │   ├── index.ts           # Entry point\n│   │   │   ├── server.ts          # MCP server setup\n│   │   │   ├── config.ts          # Configuration\n│   │   │   ├── api/\n│   │   │   │   ├── client.ts      # TiDB Cloud API client\n│   │   │   │   └── types.ts       # Type definitions\n│   │   │   ├── db/\n│   │   │   │   ├── client.ts      # Database client\n│   │   │   │   └── types.ts       # Database types\n│   │   │   └── tools/\n│   │   │       ├── index.ts       # Tool exports\n│   │   │       ├── cluster.ts     # Cluster management tools\n│   │   │       ├── branch.ts      # Branch management tools\n│   │   │       ├── database.ts    # Database SQL tools\n│   │   │       └── region.ts      # Region discovery tools\n│   │   ├── package.json\n│   │   └── tsconfig.json\n│   │\n│   └── remote/                    # Remote MCP Server (HTTP transport)\n│       ├── src/\n│       │   ├── app.ts             # Hono web app\n│       │   ├── config.ts          # Configuration\n│       │   ├── dev.ts             # Local dev server\n│       │   ├── landing.ts         # Landing page\n│       │   ├── skill.ts           # Skill documentation\n│       │   ├── worker.ts          # Cloudflare Workers entry point\n│       │   └── middleware/        # Security middleware\n│       ├── package.json\n│       └── wrangler.toml          # Cloudflare Workers configuration\n│\n├── package.json                   # Root workspace config\n├── pnpm-workspace.yaml\n└── tsconfig.base.json\n```\n\n## TiDB Cloud Limitations\n\n### Cluster Limitations\n- Serverless clusters are available in select regions (use `tidbcloud_list_regions` to see available regions)\n- Spending limits can be configured to control costs\n\n### Branch Limitations\n- Maximum 5 branches per organization (default quota)\n- Cannot branch clusters larger than 100 GiB\n- Branches are created in the same region as the parent cluster\n- Free Starter clusters: point-in-time limited to last 24 hours\n- Paid clusters: point-in-time limited to last 14 days\n\n## Security\n\n### Security Considerations\n\nThis MCP server grants powerful database management capabilities. Please review the following security guidance:\n\n- **Always review actions**: Review and authorize actions requested by the LLM before execution\n- **Development use**: This server is intended for local development and IDE integrations\n- **API key security**: Never expose your API keys in client-side code or public repositories\n- **Access control**: Ensure only authorized users have access to your MCP server URL\n- **Audit access**: Monitor usage and regularly audit who has access to your API keys\n\n### Environment Variable Security\n\n- Store API keys securely using environment variables or secret management tools\n- Never commit `.env` files containing real credentials\n- Rotate API keys periodically\n\n### Read-Only Mode\n\nFor safer operations, the `db_query` tool only allows read-only SQL statements (SELECT, SHOW, DESCRIBE, EXPLAIN). For data modifications, use `db_execute` with caution.\n\nFor more information, see the [MCP Security Best Practices](https://modelcontextprotocol.io/specification/2025-11-25/basic/security_best_practices).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flikidu%2Fmcp-server-tidbcloud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flikidu%2Fmcp-server-tidbcloud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flikidu%2Fmcp-server-tidbcloud/lists"}