Registry / gcp / mcp-bigquery-server

mcp-bigquery-server

JSON →
library1.0.5jsnpmunverified

The `mcp-bigquery-server` package provides a server implementation for the Model Context Protocol (MCP), specifically designed to enable Large Language Models (LLMs) to interact securely and efficiently with Google BigQuery datasets. Introduced in November 2024, the MCP is an open standard that facilitates standardized communication between AI systems and external data sources or tools. This server acts as an intelligent intermediary, allowing LLMs (e.g., through interfaces like Augment Code or Cursor IDE) to perform natural-language queries, inspect database schemas, list tables, and execute SQL queries against BigQuery, without direct database access. The current stable version is 1.0.5. As a relatively new and evolving standard, the project is active, with potential for feature enhancements and protocol refinements, though a strict release cadence isn't published. A key differentiator is its focus on providing secure, read-only access to BigQuery data for AI agents, streamlining data analysis workflows within development environments.

npm install mcp-bigquery-server
INSTALL
IMPORT
SIG · MCP-BIGQUERY-SERVE
M
mcp-bigquery-server
gcpjavascriptv1.0.5
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

startMcpBigQueryServer
import { startMcpBigQueryServer } from 'mcp-bigquery-server';
const startMcpBigQueryServer = require('mcp-bigquery-server').startMcpBigQueryServer;
While often run via CLI, programmatic access typically uses an async function like `startMcpBigQueryServer`. ESM is preferred.
BigQueryMcpServerConfig
import type { BigQueryMcpServerConfig } from 'mcp-bigquery-server';
import { BigQueryMcpServerConfig } from 'mcp-bigquery-server';
This is a TypeScript type for server configuration, used for strict type checking. It should be imported as a type.
createBigQueryClient
import { createBigQueryClient } from 'mcp-bigquery-server/utils';
import { createBigQueryClient } from 'mcp-bigquery-server';
Utility functions for BigQuery client instantiation might be in a submodule like 'utils' for better modularity.

This quickstart demonstrates how to programmatically start the MCP BigQuery server using a generated configuration file. It includes essential BigQuery project and dataset settings, along with a placeholder for authentication, and ensures the necessary environment variables are noted.

import { startMcpBigQueryServer } from 'mcp-bigquery-server'; import { writeFileSync } from 'fs'; import path from 'path'; // Ensure GOOGLE_APPLICATION_CREDENTIALS is set for local development or CI/CD // For production, use Workload Identity or similar GCP-native authentication if (!process.env.GOOGLE_APPLICATION_CREDENTIALS) { console.warn('WARNING: GOOGLE_APPLICATION_CREDENTIALS not set. Using default credentials or requiring manual login.'); // Example: Point to a dummy key file if running locally without actual credentials // In a real scenario, this should be a valid path to your service account key.json } // Create a minimal configuration file for the server const config = { projectId: process.env.GCP_PROJECT_ID ?? 'your-gcp-project-id', allowedDatasets: [ `${process.env.GCP_PROJECT_ID ?? 'your-gcp-project-id'}.your_dataset_name`, 'another_project.another_dataset' ], port: parseInt(process.env.PORT ?? '8080'), auth: { mode: 'none' // Or 'bearer' with tokens: ['YOUR_API_TOKEN'] } }; const configPath = path.join(process.cwd(), 'mcp-server-config.json'); writeFileSync(configPath, JSON.stringify(config, null, 2)); console.log(`MCP BigQuery Server configuration written to ${configPath}`); async function main() { try { // Start the server programmatically, passing the config directly or via file path // Alternatively, use `npx mcp-bigquery-server --config-file ./mcp-server-config.json` console.log('Starting MCP BigQuery Server...'); const server = await startMcpBigQueryServer({ config: config, logLevel: 'info' // Example: Set logging level }); console.log(`MCP BigQuery Server running on port ${server.port} for project ${server.projectId}`); console.log('Use this server with your LLM-integrated IDE (e.g., Augment Code, Cursor).'); // Keep the process alive // process.on('SIGINT', () => { // server.stop(); // process.exit(0); // }); } catch (error) { console.error('Failed to start MCP BigQuery Server:', error); process.exit(1); } } main();
Debug
Known issues
breakingAs a relatively new protocol (MCP introduced in Nov 2024), the `mcp-bigquery-server` may introduce breaking changes in minor versions or even patch releases as the protocol itself evolves. Always review release notes carefully before upgrading, especially for changes to configuration schema or exposed tool interfaces.
fix
Consult the official GitHub repository's release notes or changelog for specific version upgrade instructions. Test thoroughly in non-production environments.
affects: >=1.0.0
gotchaBigQuery costs can accumulate rapidly, especially with large or frequently executed queries. Ensure your LLM prompts are optimized to generate efficient SQL and that the server's query limits are appropriately configured to prevent unexpected billing.
fix
Implement strict `allowedDatasets` and `queryLimits` in your `config.json`. Educate LLM users on responsible querying. Monitor BigQuery usage in your Google Cloud console.
affects: >=1.0.0
gotchaCorrect IAM permissions are crucial for the service account used by the `mcp-bigquery-server`. Insufficient permissions (e.g., missing `bigquery.user` or `bigquery.dataViewer` roles) will result in 'PERMISSION_DENIED' errors when the server attempts to access BigQuery.
fix
Ensure the service account configured via `GOOGLE_APPLICATION_CREDENTIALS` (or GKE Workload Identity, etc.) has at least the `BigQuery User` role on the project and `BigQuery Data Viewer` roles on specific datasets/tables it needs to access. Grant least privilege.
affects: >=1.0.0
gotchaThe server's functionality is limited to `read-only` access to BigQuery. It cannot execute DDL (Data Definition Language) or DML (Data Manipulation Language) operations such as `CREATE TABLE`, `INSERT`, `UPDATE`, or `DELETE`. Attempting to do so via LLM prompts will fail.
fix
Design LLM interactions and application logic to respect the read-only nature of the server. If write operations are needed, consider a separate service or a different BigQuery integration approach.
affects: >=1.0.0
Errors
Common errors & fixes
Error: BigQuery API has not been used in project [project-id] before or it is disabled. Enable it by visiting...
The BigQuery API is not enabled for the specified Google Cloud project.
fix
Visit the provided URL in the Google Cloud Console to enable the BigQuery API for your project. Ensure the correct project ID is configured.
Error: Port 8080 is already in use.
The specified port (default 8080) for the MCP server is already being used by another application on the host.
fix
Change the `port` in your `config.json` file or pass a different port via command-line argument (`--port <new-port>`) when starting the server. Alternatively, stop the conflicting application.
Error: The caller does not have permission.
The authenticated service account lacks the necessary IAM permissions to access BigQuery resources (e.g., list datasets, query tables).
fix
Verify that the `GOOGLE_APPLICATION_CREDENTIALS` environment variable points to a valid service account key.json file, and that the associated service account has at least `BigQuery User` and `BigQuery Data Viewer` roles on the target project and datasets.
Failed to load configuration file: Invalid JSON format
The `config.json` file specified for the server contains syntax errors or is not valid JSON.
fix
Carefully review your `config.json` for typos, missing commas, unclosed brackets, or other JSON formatting issues. Use a JSON validator to check its correctness.
Upgrade
Version history
1.0.5latest on npm
Audit
Dependencies
@google-cloud/bigqueryrequiredEssential runtime dependency for all interactions with the Google BigQuery API. Without it, the server cannot connect to or query BigQuery.
Agent activity
20 hits · last 30 days
node
18
OpenAI (training)
1
Resources