RELATED 01
hypequery MCP server
Exposes the ClickHouse datasets and metrics you define in hypequery as bounded, read-only MCP tools
104GitHub stars
11k/wknpm downloads
58popularity score
BigQuery MCP Server
SEO analysis over the Google Search Console bulk export in BigQuery, with optional GA4 revenue joins
By Suganthan Mohanadasan (individual) TypeScript Local · stdio Data and analyticsDatabases
20 popularity score ★ 44
Connect your client
Local (from source)
Add in one click
Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.
Or add it by command or config
It needs BIGQUERY_PROJECT_ID, BIGQUERY_KEY_FILE. Replace each <NAME> with your value.
FirstTerminal
git clone https://github.com/Suganthan-Mohanadasan/Suganthans-BigQuery-MCP-Server.git
cd Suganthans-BigQuery-MCP-Server
npm install
npm run buildClaude CodeTerminal
claude mcp add bigquery -e BIGQUERY_PROJECT_ID=<BIGQUERY_PROJECT_ID> -e BIGQUERY_KEY_FILE=<BIGQUERY_KEY_FILE> -- node '<ABSOLUTE_PATH_TO_CLONE>/dist/index.js'Claude Desktopclaude_desktop_config.json
{
"mcpServers": {
"bigquery": {
"command": "node",
"args": [
"<ABSOLUTE_PATH_TO_CLONE>/dist/index.js"
],
"env": {
"BIGQUERY_PROJECT_ID": "<BIGQUERY_PROJECT_ID>",
"BIGQUERY_KEY_FILE": "<BIGQUERY_KEY_FILE>"
}
}
}
}Cursor~/.cursor/mcp.json
{
"mcpServers": {
"bigquery": {
"command": "node",
"args": [
"<ABSOLUTE_PATH_TO_CLONE>/dist/index.js"
],
"env": {
"BIGQUERY_PROJECT_ID": "<BIGQUERY_PROJECT_ID>",
"BIGQUERY_KEY_FILE": "<BIGQUERY_KEY_FILE>"
}
}
}
}VS Code.vscode/mcp.json
{
"servers": {
"bigquery": {
"type": "stdio",
"command": "node",
"args": [
"<ABSOLUTE_PATH_TO_CLONE>/dist/index.js"
],
"env": {
"BIGQUERY_PROJECT_ID": "<BIGQUERY_PROJECT_ID>",
"BIGQUERY_KEY_FILE": "<BIGQUERY_KEY_FILE>"
}
}
}
}Codex~/.codex/config.toml
[mcp_servers.bigquery]
command = "node"
args = ["<ABSOLUTE_PATH_TO_CLONE>/dist/index.js"]
[mcp_servers.bigquery.env]
BIGQUERY_PROJECT_ID = "<BIGQUERY_PROJECT_ID>"
BIGQUERY_KEY_FILE = "<BIGQUERY_KEY_FILE>"Gemini CLITerminal
gemini mcp add --scope user -e BIGQUERY_PROJECT_ID=<BIGQUERY_PROJECT_ID> -e BIGQUERY_KEY_FILE=<BIGQUERY_KEY_FILE> bigquery node -- '<ABSOLUTE_PATH_TO_CLONE>/dist/index.js'Settings 8
BIGQUERY_PROJECT_ID |
Required: Google Cloud project ID; the server will not start without it. |
|---|---|
BIGQUERY_KEY_FILE |
Required: Absolute path to the service account JSON key; GOOGLE_APPLICATION_CREDENTIALS is used instead when this is unset. |
BIGQUERY_DEFAULT_DATASET |
Optional: Default dataset, such as searchconsole; the GSC tools fall back to searchconsole. |
BIGQUERY_LOCATION |
Optional: Dataset location, US by default (for example EU). |
BIGQUERY_GA4_DATASET |
Optional: GA4 export dataset (analytics_<ID>), needed only for the ga4_gsc_* tools. |
BIGQUERY_GA4_PROJECT |
Optional: Project holding the GA4 export, when it differs from the main one (not in the README). |
BIGQUERY_GA4_LOCATION |
Optional: Location of the GA4 project's datasets when it differs (not in the README). |
GOOGLE_APPLICATION_CREDENTIALS |
Optional: Standard Google credentials path, used when BIGQUERY_KEY_FILE is unset. |
What it does
An independent server, written by Suganthan Mohanadasan, that runs SQL against the Search Console bulk export a site owner has set up in their own Google Cloud project. Most of its 33 tools are ready-made SEO analyses, so the assistant does not have to write SQL for them. They find quick-win keywords, pages losing clicks, keyword cannibalisation, CTR shortfalls against position benchmarks, new queries, search intent, device ranking splits and the share of traffic behind anonymised queries. Each result comes back as JSON with a provenance block, plus instructions telling the assistant to stick to the returned numbers and to present them as a dashboard-style artifact.
Two tools use BigQuery ML. gsc_forecast trains an ARIMA_PLUS model to project clicks 30 days ahead by default (anything from 7 to 365 days). gsc_anomalies uses the same kind of model to flag unusual days. Six ga4_gsc_* tools join the export with a GA4 BigQuery export to tie queries and pages to conversions and revenue. Six general tools (query, query_cost_estimate, list_datasets, list_tables, describe_table, sample_rows) work on any dataset in the project.
The README describes the server as read-only, but the code shows one exception. gsc_forecast and gsc_anomalies run CREATE OR REPLACE MODEL and write a model named clicks_forecast_model into the Search Console dataset, which is why the README asks for the BigQuery Data Editor role (src/tools/gsc-forecast.ts, src/tools/gsc-anomalies.ts). The code also reads two settings the README does not list, BIGQUERY_GA4_PROJECT and BIGQUERY_GA4_LOCATION, for a GA4 export that lives in a different project or region (src/client.ts).
What it needs
| Runtime | Node.js 18+ |
|---|
Node.js 18 or later, plus git and npm to clone and build it, since it is not published to npm. You need a Google Cloud project with the Search Console bulk export to BigQuery already running; the export only collects data from the day it is switched on. You also need a service account key with the BigQuery Data Editor, Data Viewer and Job User roles. BigQuery queries are billed to that project. The ga4_gsc_* tools also need the GA4 BigQuery export in place.
Limits
Covers only the BigQuery bulk export; it does not call the Search Console API, and the export holds no data from before it was enabled. The query tool returns 100 rows by default, up to 10,000 with max_rows, and appends a LIMIT when the SQL has none. Normal queries are capped at 10 GB billed and ML model training at 50 GB (src/tools/query.ts). Statements containing INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, MERGE, EXPORT, CALL or EXECUTE are refused, as are multi-statement queries. The read-only claim does not cover the forecast and anomaly tools, which overwrite a model in your dataset. The changelog notes that before v4.1.1 the gsc_* tools reported average positions one rank too good.
Who it suits
Suits SEO practitioners and site owners who already run, or are willing to set up, the Search Console bulk export in their own Google Cloud project and want unsampled analysis, anonymised-query counts, forecasts or GA4 revenue attribution. Expect BigQuery costs and a service account setup. If you only need quick lookups without BigQuery, the author's README points to a separate Search Console API server of theirs, Suganthans-GSC-MCP. If you need general BigQuery access with write tools, look for a general-purpose BigQuery server, since this one blocks data changes and is built around the Search Console export schema.
Tools 33
query- Runs one SELECT statement, with an automatic row limit and a 10 GB billing cap
query_cost_estimate- Dry-runs a SELECT and reports the bytes it would scan
list_datasets- Lists the datasets in the configured project
list_tables- Lists the tables and their schemas in a dataset
describe_table- Shows a table's column types, row count, partitioning and size
sample_rows- Returns sample rows from a table, 10 by default and up to 100
gsc_quick_wins- Scores keywords just off page one by how much traffic they could gain
gsc_ctr_opportunities- Finds pages whose CTR is below what their position would predict
gsc_content_gaps- Finds queries with demand where the site ranks poorly or not at all
gsc_site_snapshot- Summarises clicks, impressions, CTR and position against the previous period
gsc_content_decay- Flags pages that have declined over three 30-day periods in a row
gsc_cannibalisation- Lists queries where several of the site's pages compete
gsc_traffic_drops- Works out whether lost clicks come from rankings, CTR or demand
gsc_topic_cluster- Totals performance for pages matching a URL path pattern
gsc_ctr_benchmark- Compares the site's CTR at each position with industry figures
gsc_alerts- Rates recent position drops, CTR falls, click losses and vanished pages by severity
gsc_content_recommendations- Produces a ranked list of pages to update, create or merge
gsc_report- Builds a full performance report in markdown
gsc_anonymous_traffic- Measures the share of clicks and impressions with no query string
gsc_seasonal- Compares months year over year with percentage changes
gsc_device_split- Finds queries where mobile and desktop rank different pages
gsc_intent_breakdown- Groups queries into informational, transactional, commercial and navigational
gsc_ngrams- Counts recurring words and phrases across queries
gsc_new_keywords- Lists queries that appeared recently for the first time
gsc_forecast- Trains an ARIMA_PLUS model and forecasts daily clicks (writes a model to the dataset)
gsc_anomalies- Flags unusual traffic days using a BigQuery ML model (writes a model to the dataset)
gsc_genai_conversation_queries- Picks out queries that look like AI-chat fragments and sorts them into seven kinds
ga4_gsc_query_revenue- Attributes GA4 conversions and revenue to search queries by click share
ga4_gsc_content_roi- Finds pages whose rankings and conversions do not match
ga4_gsc_position_value- Shows conversion rate and revenue per click by position band
ga4_gsc_snippet_mismatch- Finds pages whose search snippet oversells or undersells the page
ga4_gsc_branded_performance- Compares conversion of branded and non-branded search traffic
ga4_gsc_page_performance- Joins search and analytics metrics per landing page