BigQuery MCP connector

What agents can do

The server has 5 actions: 4 read and 1 write.

• Explore datasets: list_datasets lists the datasets in the connected project, and list_tables lists the tables and views in a dataset.
• Read table structure: get_table_schema returns a table's columns, and get_table_metadata returns details such as row count, size, partitioning and expiration.
• Run SQL: run_query runs Standard SQL and returns up to 10,000 rows. With dry_run it reports how many bytes a query would process without running it.

Before you connect

• A Google Cloud project with BigQuery data, and permission to create service accounts and keys in it.
• A service account for InsightfulPipe. Give it BigQuery Data Viewer and BigQuery Job User for read-only use, or BigQuery Data Editor and BigQuery User if agents should also change data.
• An InsightfulPipe workspace with a brand for the project. Owners, admins and operators can add connections.

Connect BigQuery

1. In the InsightfulPipe app, open Connectors, choose BigQuery and click Connect.
2. In Google Cloud Console, open IAM & Admin → Service Accounts for your project and create a service account.
3. Grant the service account the BigQuery roles for the access you want: BigQuery Data Viewer and BigQuery Job User for read-only, or BigQuery Data Editor and BigQuery User for read and write.
4. Create a JSON key for the service account.
5. Back in InsightfulPipe, under Service Account JSON Key, choose Upload to pick the .json file, or Paste to paste the entire key.
6. Click Connect BigQuery. InsightfulPipe checks the key with Google and stores it encrypted.

Add the MCP server to your AI client

Server URL: https://bigquery.insightfulmcp.com/ and server name: bigquery-mcp.

• Claude: open Claude Connectors Settings, scroll to the bottom and click Add custom connector, paste the URL, click Add, then click Connect.
• ChatGPT: in ChatGPT Security Settings turn on Developer mode, click Create on the Connectors page, paste the URL, click Create, then click Connect. Turn the connector on in each new chat with + → More.
• Claude Code: run claude mcp add --transport http bigquery-mcp https://bigquery.insightfulmcp.com/, then type /mcp, select bigquery-mcp and click Authenticate.
• Cursor: in the app, open MCP Servers, choose BigQuery and click Install BigQuery MCP, click Open Cursor then Install, then click Connect and Open.
• Gemini CLI: run gemini mcp add --transport http bigquery-mcp https://bigquery.insightfulmcp.com/, then /mcp auth bigquery-mcp.
• Codex CLI: run codex mcp add bigquery-mcp --url https://bigquery.insightfulmcp.com/; authorization starts automatically.

Each client opens a browser window where you log in to InsightfulPipe and click Authorize access. Step-by-step guides: Claude, ChatGPT, Claude Code, Cursor, Gemini CLI and Codex CLI. To reach every connected platform through one server, use the unified server.

Permissions and safety

• No Read Only mode: BigQuery connections have no Read Only or Read + Write choice in InsightfulPipe. The IAM roles on the service account decide whether a statement succeeds.
• What counts as a write: a request is a read only when it is a single SELECT statement with no INTO and no data-changing CTE. Any other SQL, such as INSERT, UPDATE, MERGE, CREATE or DROP, or several statements in one request, is a write.
• Where writes run: the read-only query_data tool refuses writes, so they run only through execute_action, and only for members with the Owner, Administrator or Operator role.
• On by default: run_query is enabled on a new connection. To limit agents to datasets, schemas and metadata, an owner, admin or operator can turn it off in Configure actions for this account.
• Keep it read-only: give the service account only BigQuery Data Viewer and BigQuery Job User, so BigQuery itself rejects writes.
• Restricted members: members with the User role only get the read actions enabled on projects granted to them.

Limits

• Rows: run_query returns up to 10,000 rows per query, 1,000 by default.
• Query size: query text can be up to 256 KB.
• Wait time: a query waits up to 300 seconds for results (timeout_ms, 30 seconds by default). A query that runs longer returns a job reference without rows.
• Cost: InsightfulPipe sets no bytes-billed cap, and Google bills queries to your project as usual. Use dry_run to check how many bytes a query will process before running it.
• One project per connection: each connection is one Google Cloud project with its own key.
• No admin actions: there are no actions for creating datasets or listing jobs.

Example prompts

• "Which datasets are in this BigQuery project?"
• "Describe the columns in the analytics.events table."
• "How many bytes would this query scan? Don't run it yet."
• "Show the top 10 landing pages by sessions last week from our GA4 export."

Troubleshooting

• The key is rejected when you connect: paste or upload the entire JSON key for the service account, and check that the key still exists in Google Cloud Console.
• BigQuery returns an access denied error: the service account is missing a role. Add BigQuery Job User to run queries and BigQuery Data Viewer on the data, or BigQuery Data Editor and BigQuery User for writes.
• "This action modifies data and cannot run through the read-only query_data tool. Send the same body through execute_action instead." The SQL is not a single SELECT, so it must run through execute_action.
• "Your role does not have permission to execute write actions. Only operators, admins, and owners can execute write operations." Members with the User role can't run writes. Ask a workspace admin to change your role.
• "This action is disabled for this connected account. An owner or admin must enable it for the account." An owner, admin or operator can turn on run_query in Configure actions for this account.
• A query returns a job reference and no rows: it ran past its wait time. Raise timeout_ms up to 300,000, or narrow the query with filters, a partition or a LIMIT.

FAQ

Can agents change data in BigQuery?

Only when the service account's IAM roles allow it and the member has the Owner, Administrator or Operator role. A single SELECT runs as a read; any other SQL is a write that runs through execute_action.

Who pays for the queries?

Google bills query processing to your Google Cloud project, as with any other BigQuery client. Your InsightfulPipe plan covers the MCP server, not BigQuery usage.

Can I connect with a Google sign-in instead of a key?

No. New BigQuery connections use a service account JSON key.

Can I connect several Google Cloud projects?

Yes. Each project is its own connection with its own key, and each connection counts toward your plan's connection limit.

Related

• BigQuery MCP server
• PostgreSQL, MySQL and SQL Server connectors
• Google Sheets connector
• Roles and permissions
• MCP troubleshooting