query
Run a read-only BigQuery SQL query
LABSCO SUMMARY
A warehouse an agent can be pointed at without a conversation about permissions first.
The entire surface is one read-only query tool, which is what makes it easy to hand to a model: there is no write, no load and no schema-change path to fence off. What it does not carry is discovery — nothing lists datasets, tables or columns — so the schema has to come from you or from a query the agent already knows how to write.
What it is
A single-tool server over BigQuery that runs read-only SQL and returns the result.
What you get
- Read-only BigQuery SQL run from the conversation, with the rows returned into it
- The project fixed when the server starts, so each call carries only its sql
- A single entry point, which makes what the agent can do here exactly what a read-only SQL user can do
Requirements
A BigQuery project and credentials on the machine that can read it. The project id is supplied when the server starts rather than per query.
Setup effort
One command plus credentials — npx -y @ergut/mcp-bigquery-server --project-id <YOUR_PROJECT_ID>, then supply credentials
USE CASES
01
Answering a data question without opening the console
Write the SQL, get the rows back in the conversation, and iterate on the query there. The connection reads and nothing more, so an exploratory query cannot change anything.
1 tool
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
BEFORE YOU INSTALL
What to know first
Tools you get
1 tool when we connected.
Requires
- Node.js 14 or higher
- Google Cloud project with BigQuery enabled
- Either Google Cloud CLI installed or a service account key file
- Any MCP-compatible client (Claude Desktop, Claude Code, etc.)
CONTEXT COST
Light Standing cost
Rated by the size of the one tool definition that rides along on every turn
INSTALLATION
Connect your client
Server setup
Build from source
Clone and install
TERMINAL
git clone https://github.com/ergut/mcp-bigquery-server
cd mcp-bigquery-server
npm installBuild
TERMINAL
npm run buildnpx
TERMINAL
npx -y @ergut/mcp-bigquery-server --project-id <YOUR_PROJECT_ID>MCP Clients
Claude Desktop, Claude Code
Authenticate with Google Cloud first:
TERMINAL
gcloud auth application-default loginThen add this to your client config (claude_desktop_config.json for Claude Desktop, .mcp.json for Claude Code):
{
"mcpServers": {
"bigquery": {
"command": "npx",
"args": [
"-y",
"@ergut/mcp-bigquery-server",
"--project-id",
"<YOUR_PROJECT_ID>"
]
}
}
}<YOUR_PROJECT_ID> is your Google Cloud project ID. To use a service account key instead of gcloud, skip the login and add "--key-file", "/path/to/service-account-key.json" to args, with the full path of the key file you downloaded from Google Cloud.
Any MCP client — Local Build
Build the clone (Build it from source above), authenticate with gcloud auth application-default login, then point your client at the build:
ANY MCP CLIENT — LOCAL BUILD · JSON
{
"mcpServers": {
"bigquery": {
"command": "node",
"args": [
"<YOUR_PATH_TO_CLONE>/mcp-bigquery-server/dist/index.js",
"--project-id",
"<YOUR_PROJECT_ID>",
"--location",
"us-central1"
]
}
}
}<YOUR_PATH_TO_CLONE> is the full path of your clone (npm run build creates dist/index.js there). For a service account, add "--key-file", "/path/to/service-account-key.json" to args.
