mcp-bigquery-server

CostingGeek/mcp-bigquery-server

3.2

If you are the rightful owner of mcp-bigquery-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server that connects Claude AI to SAP data in Google BigQuery for natural language querying and analysis.

Tools
3
Resources
0
Prompts
0

BigQuery MCP Server for SAP Data Analysis

A Model Context Protocol (MCP) server that provides Claude Code and Claude Desktop with direct access to SAP data stored in Google BigQuery. This enables natural language querying and analysis of enterprise SAP data.

License: MIT

Overview

This project demonstrates how to build an MCP server that:

  • Connects Claude AI to Google BigQuery datasets
  • Enables natural language SQL queries on SAP Cortex data
  • Deploys as a serverless Google Cloud Run Function
  • Integrates with both Claude Code CLI and Claude Desktop

Features

  • 3 MCP Tools:

    • list_tables - List all tables in the BigQuery dataset
    • describe_table - Get schema information for any table
    • query_bigquery - Execute SQL queries and return results

  • Dual Deployment:

    • Local MCP server for Claude Code/Desktop
    • Cloud-hosted HTTP endpoint on Google Cloud Run

  • Enterprise Ready:

    • Handles complex SAP data structures
    • Supports date/time/numeric serialization
    • CORS-enabled for web integrations

Architecture

┌─────────────────┐
│  Claude Code    │
│  Claude Desktop │
└────────┬────────┘
         │
         ├─────────────────┐
         │                 │
    ┌────▼─────┐     ┌────▼──────────────┐
    │ MCP      │     │ Cloud Run         │
    │ Wrapper  │     │ Function          │
    │ (Local)  │     │ (HTTP Endpoint)   │
    └────┬─────┘     └────┬──────────────┘
         │                │
         └────────┬───────┘
                  │
           ┌──────▼───────┐
           │  BigQuery    │
           │  Dataset     │
           └──────────────┘

Prerequisites

Required

  • Python 3.13+
  • Node.js 18+ and npm
  • Google Cloud account with billing enabled
  • Google Cloud SDK (gcloud CLI)
  • BigQuery dataset with data

Optional

  • Claude Code CLI (npm install -g @anthropic-ai/claude-code)
  • Claude Desktop application

Installation

1. Clone the Repository

git clone https://github.com/yourusername/mcp-bigquery-server.git
cd mcp-bigquery-server

2. Install Python Dependencies

pip install -r requirements.txt

3. Configure Google Cloud

# Set your project
gcloud config set project YOUR_PROJECT_ID

# Authenticate
gcloud auth login
gcloud auth application-default login

# Create service account (optional but recommended)
gcloud iam service-accounts create bigquery-mcp-server \
  --display-name="BigQuery MCP Server"

# Grant BigQuery permissions
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:bigquery-mcp-server@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/bigquery.user"

4. Update Configuration

Edit server.py and main.py to set your project and dataset:

PROJECT_ID = "your-project-id"
DATASET_ID = "your-dataset-name"

Update mcp_wrapper.js with your Cloud Run URL (after deployment):

const MCP_SERVER_URL = 'your-region-your-project.cloudfunctions.net';
const MCP_SERVER_PATH = '/bigquery-mcp-server';

Deployment

Deploy to Google Cloud Run

gcloud functions deploy bigquery-mcp-server \
  --gen2 \
  --runtime=python313 \
  --region=us-west1 \
  --source=. \
  --entry-point=bigquery_mcp_handler \
  --trigger-http \
  --allow-unauthenticated \
  --service-account=bigquery-mcp-server@YOUR_PROJECT_ID.iam.gserviceaccount.com \
  --set-env-vars GCP_PROJECT_ID=YOUR_PROJECT_ID,DATASET_ID=YOUR_DATASET_NAME

Note: The function will output a URL like:

https://REGION-PROJECT_ID.cloudfunctions.net/bigquery-mcp-server

Save this URL - you'll need it for the MCP wrapper configuration.

Configuration

For Claude Code CLI

Add the MCP server:

claude mcp add bigquery-sap node /path/to/mcp_wrapper.js

Verify connection:

claude mcp list

For Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (Mac):

{
  "mcpServers": {
    "bigquery-sap": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_wrapper.js"]
    }
  }
}

Restart Claude Desktop to load the configuration.

Usage

In Claude Desktop

Ask Claude natural language questions:

"List all tables in the BigQuery dataset"

"Query the SalesOrders table and show me the top 10 orders by value"

"Analyze sales trends by month from the AccountingDocuments table"

In Claude Code CLI

claude "Use the list_tables tool to show all available tables"

claude "Query the inventory data and identify slow-moving items"

Direct HTTP API

# List tables
curl -X POST https://YOUR-FUNCTION-URL/bigquery-mcp-server \
  -H "Content-Type: application/json" \
  -d '{"action": "list_tables"}'

# Query data
curl -X POST https://YOUR-FUNCTION-URL/bigquery-mcp-server \
  -H "Content-Type: application/json" \
  -d '{"action": "query", "query": "SELECT * FROM dataset.table LIMIT 10"}'

Project Structure

mcp-bigquery-server/
├── server.py              # Core MCP server logic
├── main.py                # Cloud Function HTTP handler
├── mcp_wrapper.js         # Local MCP protocol wrapper
├── requirements.txt       # Python dependencies
├── .gcloudignore         # Files to exclude from deployment
├── .gitignore            # Git ignore rules
├── README.md             # This file
├── CLAUDE_CODE_USAGE.md  # Detailed usage guide
└── LICENSE               # MIT license

Security Considerations

⚠️ Important Security Notes:

  1. Never commit service account keys - They're excluded via .gitignore
  2. Use IAM roles instead of service account keys in production
  3. Restrict BigQuery access to only necessary datasets/tables
  4. Consider authentication for the Cloud Run endpoint in production
  5. Use VPC Service Controls for additional security in enterprise environments

Troubleshooting

MCP Server Not Connecting

# Check server health
claude mcp list

# Test MCP wrapper directly
node mcp_wrapper.js
{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

BigQuery Permission Errors

# Verify service account permissions
gcloud projects get-iam-policy YOUR_PROJECT_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:YOUR_SERVICE_ACCOUNT"

Cloud Function Deployment Issues

# View function logs
gcloud functions logs read bigquery-mcp-server --region=us-west1

# Check function status
gcloud functions describe bigquery-mcp-server --region=us-west1

Use Cases

  • Financial Analysis: Query P&L statements, balance sheets, and accounting documents
  • Sales Analytics: Analyze order trends, customer behavior, and revenue metrics
  • Inventory Management: Track stock levels, movements, and turnover rates
  • Procurement: Monitor vendor performance, PO fulfillment, and spend analysis
  • Executive Dashboards: Create real-time KPI reports from live SAP data

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

Resources

Author

Julien Delvat

Support

For issues and questions:

  • Open an issue on GitHub
  • Check the for detailed examples

Note: This is a reference implementation. Please review and adjust security settings, IAM permissions, and configurations according to your organization's requirements before deploying to production.