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

Related MCP server: My Credentials MCP Server

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)

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.

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