
mcp-bigquery-server
A Model Context Protocol (MCP) server that provides secure, read-only access to BigQuery datasets. Enables Large Language Models (LLMs) to safely query and analyze data through a standardized interface.
2
Github Watches
14
Github Forks
47
Github Stars
BigQuery MCP Server

What is this? 🤔
This is a server that lets your LLMs (like Claude) talk directly to your BigQuery data! Think of it as a friendly translator that sits between your AI assistant and your database, making sure they can chat securely and efficiently.
Quick Example
You: "What were our top 10 customers last month?"
Claude: *queries your BigQuery database and gives you the answer in plain English*
No more writing SQL queries by hand - just chat naturally with your data!
How Does It Work? 🛠️
This server uses the Model Context Protocol (MCP), which is like a universal translator for AI-database communication. While MCP is designed to work with any AI model, right now it's available as a developer preview in Claude Desktop.
Here's all you need to do:
- Set up authentication (see below)
- Add your project details to Claude Desktop's config file
- Start chatting with your BigQuery data naturally!
What Can It Do? 📊
- Run SQL queries by just asking questions in plain English
- Access both tables and materialized views in your datasets
- Explore dataset schemas with clear labeling of resource types (tables vs views)
- Analyze data within safe limits (1GB query limit by default)
- Keep your data secure (read-only access)
Quick Start 🚀
Prerequisites
- Node.js 14 or higher
- Google Cloud project with BigQuery enabled
- Either Google Cloud CLI installed or a service account key file
- Claude Desktop (currently the only supported LLM interface)
Option 1: Quick Install via Smithery (Recommended)
To install BigQuery MCP Server for Claude Desktop automatically via Smithery, run this command in your terminal:
npx @smithery/cli install @ergut/mcp-bigquery-server --client claude
The installer will prompt you for:
- Your Google Cloud project ID
- BigQuery location (defaults to us-central1)
Once configured, Smithery will automatically update your Claude Desktop configuration and restart the application.
Option 2: Manual Setup
If you prefer manual configuration or need more control:
-
Authenticate with Google Cloud (choose one method):
- Using Google Cloud CLI (great for development):
gcloud auth application-default login
- Using a service account (recommended for production):
# Save your service account key file and use --key-file parameter # Remember to keep your service account key file secure and never commit it to version control
- Using Google Cloud CLI (great for development):
-
Add to your Claude Desktop config Add this to your
claude_desktop_config.json
:-
Basic configuration:
{ "mcpServers": { "bigquery": { "command": "npx", "args": [ "-y", "@ergut/mcp-bigquery-server", "--project-id", "your-project-id", "--location", "us-central1" ] } } }
-
With service account:
{ "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" ] } } }
-
-
Start chatting! Open Claude Desktop and start asking questions about your data.
Command Line Arguments
The server accepts the following arguments:
-
--project-id
: (Required) Your Google Cloud project ID -
--location
: (Optional) BigQuery location, defaults to 'us-central1' -
--key-file
: (Optional) Path to service account key JSON file
Example using service account:
npx @ergut/mcp-bigquery-server --project-id your-project-id --location europe-west1 --key-file /path/to/key.json
Permissions Needed
You'll need one of these:
-
roles/bigquery.user
(recommended) - OR both:
-
roles/bigquery.dataViewer
-
roles/bigquery.jobUser
-
Developer Setup (Optional) 🔧
Want to customize or contribute? Here's how to set it up locally:
# Clone and install
git clone https://github.com/ergut/mcp-bigquery-server
cd mcp-bigquery-server
npm install
# Build
npm run build
Then update your Claude Desktop config to point to your local build:
{
"mcpServers": {
"bigquery": {
"command": "node",
"args": [
"/path/to/your/clone/mcp-bigquery-server/dist/index.js",
"--project-id",
"your-project-id",
"--location",
"us-central1",
"--key-file",
"/path/to/service-account-key.json"
]
}
}
}
Current Limitations ⚠️
- MCP support is currently only available in Claude Desktop (developer preview)
- Connections are limited to local MCP servers running on the same machine
- Queries are read-only with a 1GB processing limit
- While both tables and views are supported, some complex view types might have limitations
Support & Resources 💬
License 📝
MIT License - See LICENSE file for details.
Author ✍️
Salih Ergüt
Sponsorship
This project is proudly sponsored by:
Version History 📋
See CHANGELOG.md for updates and version history.
相关推荐
I find academic articles and books for research and literature reviews.
Confidential guide on numerology and astrology, based of GG33 Public information
Converts Figma frames into front-end code for various mobile frameworks.
Advanced software engineer GPT that excels through nailing the basics.
Take an adjectivised noun, and create images making it progressively more adjective!
Embark on a thrilling diplomatic quest across a galaxy on the brink of war. Navigate complex politics and alien cultures to forge peace and avert catastrophe in this immersive interstellar adventure.
Discover the most comprehensive and up-to-date collection of MCP servers in the market. This repository serves as a centralized hub, offering an extensive catalog of open-source and proprietary MCP servers, complete with features, documentation links, and contributors.
Micropython I2C-based manipulation of the MCP series GPIO expander, derived from Adafruit_MCP230xx
The all-in-one Desktop & Docker AI application with built-in RAG, AI agents, No-code agent builder, MCP compatibility, and more.
Bridge between Ollama and MCP servers, enabling local LLMs to use Model Context Protocol tools
🧑🚀 全世界最好的LLM资料总结(Agent框架、辅助编程、数据处理、模型训练、模型推理、o1 模型、MCP、小语言模型、视觉语言模型) | Summary of the world's best LLM resources.
Fair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.
Reviews

user_QZIP2Nnl
As a dedicated user of mcp applications, I must say that the mcp-bigquery-server by ergut is incredibly impressive. This tool greatly simplifies querying BigQuery databases and makes data handling much more efficient. The seamless integration and straightforward setup make it a must-have for any data professional. Highly recommended!