mcp-bigquery

The BigQuery MCP Server acts as a translator between your AI assistant (currently Claude Desktop during developer preview) and your Google BigQuery data. It lets you ask in plain language for data insights, and the server translates those natural language queries into BigQuery SQL under the hood and returns human-friendly results. You can explore dataset schemas, access both tables and materialized views, and run read-only queries with a default 1GB processing limit. To use it, configure the MCP server in Claude Desktop (or your supported MCP client) to point to the bigquery MCP server, then start asking questions about your data.

Once configured, you can ask questions like: “What were our top customers last month?” or “Show me the revenue by region for the last quarter.” The server will translate these requests into appropriate BigQuery queries, fetch the results, and present them in an easy-to-understand format. Remember that this setup is read-only, so you won’t be able to perform data modification operations through the MCP interface.

Prerequisites:

• Node.js 14 or higher installed on your machine
• npm (comes with Node.js) or yarn
• A Google Cloud project with BigQuery enabled
• Claude Desktop (as the current supported MCP client for this server)

Option A: Quick Install via Smithery (Recommended)

1. Install the MCP server using Smithery:

npx @smithery/cli install @ergut/mcp-bigquery-server --client claude

2. During setup, provide your Google Cloud project ID and BigQuery location (defaults to us-central1). Smithery will update Claude Desktop configuration and restart the app.

Option B: Manual Setup

1. Authenticate with Google Cloud (choose one):

   • Developer setup with Google Cloud CLI:

     gcloud auth application-default login
     

   • Service account (production recommended): create or obtain a JSON key file and keep it secure

     # Save your service account key file and reference it via --key-file if you use the CLI
     

2. Add to Claude Desktop config (example):

   • Basic configuration:

     {
       "mcpServers": {
         "bigquery": {
           "command": "npx",
           "args": [
             "-y",
             "@ergut/mcp-bigquery-server",
             "--project-id",
             "your-project-id",
             "--location",
             "us-central1"
           ]
         }
       }
     }
     

   • With a service account key-file:

     {
       "mcpServers": {
         "bigquery": {
           "command": "npx",
           "args": [
             "-y",
             "@ergut/mcp-bigquery-server",
             "--project-id",
             "your-project-id",
             "--location",
             "us-central1",
             "--key-file",
             "/path/to/service-account-key.json"
           ]
         }
       }
     }
     

3. Start chatting: Open Claude Desktop and begin asking questions about your data.

4. Runtime example (CLI):

npx @ergut/mcp-bigquery-server --project-id your-project-id --location us-central1

Tips and common issues:

• Ensure your Google Cloud project has BigQuery enabled and that the account you use has read-only access (roles/bigquery.user or a combination of dataViewer and jobUser).
• If using a service account, never commit the key file to version control and keep it secure.
• The MCP server runs as a local or remote service; if Claude Desktop cannot reach it, verify network access and that the server process is running.
• The default 1GB processing limit applies to queries. For heavier needs, consider adjusting quotas or ensuring your accounting aligns with BigQuery pricing.
• The CLI and config examples show how to pass --project-id, --location, and optional --key-file. You can customize these values to fit your environment.
• This server currently targets Claude Desktop via MCP in developer preview; support may expand to other MCP clients in the future.