BigQuery MCP Server

1# BigQuery MCP Server
2[![smithery badge](https://smithery.ai/badge/@ergut/mcp-bigquery-server)](https://smithery.ai/protocol/@ergut/mcp-bigquery-server)
3<div align="center">
4  <img src="assets/mcp-bigquery-server-logo.png" alt="BigQuery MCP Server Logo" width="400"/>
5</div>
6 
7## What is this? 🤔
8 
9This 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.
10 
11### Quick Example
12```text
13You: "What were our top 10 customers last month?"
14Claude: *queries your BigQuery database and gives you the answer in plain English*
15```
16 
17No more writing SQL queries by hand - just chat naturally with your data!
18 
19## How Does It Work? 🛠️
20 
21This 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.
22 
23Here's all you need to do:
241. Set up authentication (see below)
252. Add your project details to Claude Desktop's config file
263. Start chatting with your BigQuery data naturally!
27 
28### What Can It Do? 📊
29 
30- Run SQL queries by just asking questions in plain English
31- Access both tables and materialized views in your datasets
32- Explore dataset schemas with clear labeling of resource types (tables vs views)
33- Analyze data within safe limits (1GB query limit by default)
34- Keep your data secure (read-only access)
35 
36## Quick Start 🚀
37 
38### Prerequisites
39- Node.js 14 or higher
40- Google Cloud project with BigQuery enabled
41- Either Google Cloud CLI installed or a service account key file
42- Claude Desktop (currently the only supported LLM interface)
43 
44### Option 1: Quick Install via Smithery (Recommended)
45To install BigQuery MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/protocol/@ergut/mcp-bigquery-server), run this command in your terminal:
46 
47```bash
48npx @smithery/cli install @ergut/mcp-bigquery-server --client claude
49```
50The installer will prompt you for:
51 
52- Your Google Cloud project ID
53- BigQuery location (defaults to us-central1)
54 
55Once configured, Smithery will automatically update your Claude Desktop configuration and restart the application.
56 
57### Option 2: Manual Setup
58If you prefer manual configuration or need more control:
59 
601. **Authenticate with Google Cloud** (choose one method):
61   - Using Google Cloud CLI (great for development):
62     ```bash
63     gcloud auth application-default login
64     ```
65   - Using a service account (recommended for production):
66     ```bash
67     # Save your service account key file and use --key-file parameter
68     # Remember to keep your service account key file secure and never commit it to version control
69     ```
70 
712. **Add to your Claude Desktop config**
72   Add this to your `claude_desktop_config.json`:
73 
74   - Basic configuration:
75     ```json
76     {
77       "mcpServers": {
78         "bigquery": {
79           "command": "npx",
80           "args": [
81             "-y",
82             "@ergut/mcp-bigquery-server",
83             "--project-id",
84             "your-project-id",
85             "--location",
86             "us-central1"
87           ]
88         }
89       }
90     }
91     ```
92 
93   - With service account:
94     ```json
95     {
96       "mcpServers": {
97         "bigquery": {
98           "command": "npx",
99           "args": [
100             "-y",
101             "@ergut/mcp-bigquery-server",
102             "--project-id",
103             "your-project-id",
104             "--location",
105             "us-central1",
106             "--key-file",
107             "/path/to/service-account-key.json"
108           ]
109         }
110       }
111     }
112     ```
113     
114 
1153. **Start chatting!** 
116   Open Claude Desktop and start asking questions about your data.
117 
118### Command Line Arguments
119 
120The server accepts the following arguments:
121- `--project-id`: (Required) Your Google Cloud project ID
122- `--location`: (Optional) BigQuery location, defaults to 'us-central1'
123- `--key-file`: (Optional) Path to service account key JSON file
124 
125Example using service account:
126```bash
127npx @ergut/mcp-bigquery-server --project-id your-project-id --location europe-west1 --key-file /path/to/key.json
128```
129 
130### Permissions Needed
131 
132You'll need one of these:
133- `roles/bigquery.user` (recommended)
134- OR both:
135  - `roles/bigquery.dataViewer`
136  - `roles/bigquery.jobUser`
137 
138## Developer Setup (Optional) 🔧
139 
140Want to customize or contribute? Here's how to set it up locally:
141 
142```bash
143# Clone and install
144git clone https://github.com/ergut/mcp-bigquery-server
145cd mcp-bigquery-server
146npm install
147 
148# Build
149npm run build
150```
151 
152Then update your Claude Desktop config to point to your local build:
153```json
154{
155  "mcpServers": {
156    "bigquery": {
157      "command": "node",
158      "args": [
159        "/path/to/your/clone/mcp-bigquery-server/dist/index.js",
160        "--project-id",
161        "your-project-id",
162        "--location",
163        "us-central1",
164        "--key-file",
165        "/path/to/service-account-key.json"
166      ]
167    }
168  }
169}
170```
171 
172## Current Limitations ⚠️
173 
174- MCP support is currently only available in Claude Desktop (developer preview)
175- Connections are limited to local MCP servers running on the same machine
176- Queries are read-only with a 1GB processing limit
177- While both tables and views are supported, some complex view types might have limitations
178 
179## Support & Resources 💬
180 
181- 🐛 [Report issues](https://github.com/ergut/mcp-bigquery-server/issues)
182- 💡 [Feature requests](https://github.com/ergut/mcp-bigquery-server/issues)
183- 📖 [Documentation](https://github.com/ergut/mcp-bigquery-server)
184 
185## License 📝
186 
187MIT License - See [LICENSE](LICENSE) file for details.
188 
189## Author ✍️ 
190 
191Salih Ergüt
192 
193## Sponsorship
194 
195This project is proudly sponsored by:
196 
197<div align="center">
198  <a href="https://www.oredata.com">
199    <img src="assets/oredata-logo-nobg.png" alt="OREDATA" width="300"/>
200  </a>
201</div>
202 
203## Version History 📋
204 
205See [CHANGELOG.md](CHANGELOG.md) for updates and version history.