bytebase-mcp

MCP server for Bytebase — SQL Editor, schema catalog, query history, and the full change-plan workflow over the Connect-RPC API. Authentication is the standard MCP OAuth 2.1 flow (PKCE public client, dynamic registration) — the same flow MCP clients like Claude Code and opencode run against remote MCP servers.

No browser automation. No static tokens. No background daemon. No bundled certificates — everything resolves from environment variables.

Authentication model

Implements the MCP SDK's OAuthClientProvider + auth():

RFC 9728 protected-resource discovery → authorization-server metadata → RFC 7591 dynamic client registration → PKCE (S256) authorization-code flow
One token file per instance (~/.config/bytebase-mcp/<host>.json, mode 600) is the only credential store
Refresh under an atomic mkdir lock — the one filesystem operation that is atomic on both Windows and POSIX — and the file is re-read after taking the lock, so a process that loses the race picks up the winner's tokens. This matters: Bytebase's refresh token is single-use with no reuse grace, and MCP clients spawn one process per session, all sharing one grant
Single-flight within a process: concurrent 401s share one refresh
Access tokens re-mint on demand; the 1-hour expiry never surfaces
401 self-heal: the client passes the stale token to the refresh path, so cross-process rotation is detected, never double-burned

Setup

npm install
cp .env.example .env        # set BYTEBASE_URL
npm run build

npm run auth                # standard MCP OAuth 2.1 login (prints the approval URL)
npm run auth:status         # grant health, no secrets
npm run probe               # preflight: TLS, grant, identity, projects

The login prints a URL; open it in any browser, approve, and the loopback listener captures the redirect. Re-login is needed roughly every 30 days.

MCP configuration

{
  "mcpServers": {
    "bytebase": {
      "command": "node",
      "args": ["C:/path/to/bytebase-mcp/dist/index.js"],
      "env": { "BYTEBASE_URL": "https://bytebase.example.com" }
    }
  }
}

Tools (14)

Tool	Description
`bytebase_whoami`	Identity, server version, token life, visible projects — run first when debugging auth
`bytebase_list_projects`	Projects the identity can see
`bytebase_list_databases`	Databases with instance/engine/environment (the `ref` feeds other tools)
`bytebase_search_tables`	Find tables by name/column (~1000-table prod DBs)
`bytebase_describe_table`	Columns, indexes, foreign keys
`bytebase_query`	SQL through the SQL Editor — read-only by default (SELECT/WITH/SHOW/DESCRIBE/EXPLAIN), routed to the read-only replica when one exists; write SQL requires `BYTEBASE_ALLOW_WRITE=true`
`bytebase_query_history`	Recent queries recorded by Bytebase
`bytebase_list_issues`	Schema/data change issues with approval status
`bytebase_create_plan`	Draft a SQL change plan (Sheet + Plan) — no SQL runs until a human approves
`bytebase_get_plan`	Plan details incl. decoded SQL
`bytebase_update_plan`	Edit title/description/SQL of a draft or in-review plan
`bytebase_list_issue_labels`	Labels a project requires on review issues
`bytebase_submit_plan_for_review`	Open the review Issue — starts the approval workflow
`bytebase_close_plan`	Cancel a draft or its open review issue (refuses after rollout starts)

Write safety: bytebase_query blocks writes by default; the plan workflow is the write route — it creates a reviewable proposal that only executes after human approval in the Bytebase UI.

Environment variables

All configuration is environment-driven — nothing site-specific is bundled.

Variable	Default	Purpose
`BYTEBASE_URL`	—	Instance base URL (required)
`BYTEBASE_MCP_HOME`	`~/.config/bytebase-mcp`	Token file location
`BYTEBASE_CALLBACK_PORT`	`51789`	Loopback OAuth redirect port
`BYTEBASE_ALLOW_WRITE`	unset	Allow write SQL in `bytebase_query`
`BYTEBASE_DEFAULT_LIMIT` / `BYTEBASE_MAX_LIMIT`	200 / 5000	Row caps
`BYTEBASE_PROXY` / `HTTPS_PROXY`	—	Outbound proxy
`BYTEBASE_CA_FILE` / `NODE_EXTRA_CA_CERTS`	—	Extra CA for servers with an incomplete cert chain

Development

npm run typecheck && npm run build && npm test
npm run probe                                    # live preflight against .env
node test/mcp-e2e.mjs                            # full stdio protocol test (needs auth)

Releasing

CI runs on every push and PR (typecheck → build → tests). Publishing is GitHub-Release-driven:

# 1. Bump "version" in package.json, commit and push to main
# 2. Create a GitHub Release (web UI, or):
gh release create v0.2.1 --generate-notes --repo ahmedbally/bytebase-mcp

On publish, the workflow verifies the release tag matches package.json, runs the full verification, publishes to npm (via the NPM_TOKEN secret), and appends the published version to the release notes.

License

MIT