mcp-timescale

Read-only MCP server for TimescaleDB and PostgreSQL databases that acts on the caller’s identity. An agent gets the catalog (schemas, tables, hypertables, chunks, continuous aggregates, background jobs) and a guarded SELECT surface; the server gets the person behind every call and refuses to run as nobody.

Built on mark3labs/mcp-go, giantswarm/mcp-oauth (OAuth 2.1 resource server, token forwarding) and giantswarm/mcp-toolkit (logging, tracing, health, response cap and per-tool timeout middleware); jackc/pgx talks to PostgreSQL.

Installation

Every release carries one binary per platform (mcp-timescale--: linux, darwin and windows on amd64 and arm64) next to its cosign Sigstore bundle (.bundle), the multi-arch image gsoci.azurecr.io/giantswarm/mcp-timescale: and the chart in the Giant Swarm catalog.

# a release binary (verify by hand with cosign v3: verify-blob --bundle .bundle)
curl -fsSLo mcp-timescale https://github.com/giantswarm/mcp-timescale/releases/latest/download/mcp-timescale-linux-amd64
chmod +x mcp-timescale

# or from source
go install github.com/giantswarm/mcp-timescale@latest

An installed binary keeps itself current:

mcp-timescale self-update

self-update downloads the latest release’s binary together with its bundle and installs it only after the bundle verifies for a CircleCI build of giantswarm/mcp-timescale against the Sigstore public-good trust root. A release without a bundle, or a download that does not match its signature, is refused and the installed binary stays as it is.

CLI

mcp-timescale               # same as `mcp-timescale serve`
mcp-timescale serve         # --transport stdio|sse|streamable-http, --mcp-addr, --metrics-addr, --databases-file, --debug
mcp-timescale version       # version, commit and build time
mcp-timescale self-update   # verified update to the latest release

version and --version report the release version; a plain go build reports Go’s VCS build info (+dirty with untracked files), the generated make build stamps the same identifiers the CI does (pkg/project).

There is no --read-only or --non-destructive switch as in mcp-capi or mcp-kubernetes: every tool is read-only by construction, except timescale_insert_row, which exists only when a database configures an insert path (see Inserting rows). tools.ReadOnlyTools and tools.WriteTools are the whole tool classification, the tool tests