BigQuery MCP Server - Complete Workflow Guide

How All Files Connect Together

┌─────────────────────────────────────────────────────────────────┐
│                        YOUR APPLICATION                          │
│                    (MCP Client/Claude)                          │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ Calls MCP Tools
                             ↓
┌─────────────────────────────────────────────────────────────────┐
│                       src/server.py                             │
│  • Registers MCP tools (auth, list_tables, run_query, etc.)    │
│  • Routes tool calls to handlers                               │
│  • Main entry point: python -m src.server                      │
└──────────┬──────────────────────────┬───────────────────────────┘
           │                          │
           │ Uses                     │ Uses
           ↓                          ↓
┌──────────────────────┐    ┌─────────────────────────┐
│    src/auth.py       │    │  src/bigquery_client.py │
│  • Authenticates     │    │  • Connects to BigQuery │
│  • Manages tokens    │    │  • Executes queries     │
│  • Manages sessions  │    │  • Gets table info      │
└──────────────────────┘    └─────────────────────────┘
           ↑                          ↑
           │ Uses                     │ Uses
           │                          │
┌──────────┴──────────────────────────┴───────────────────────────┐
│                       src/config.py                             │
│  • Loads .env file                                              │
│  • Provides configuration (SECRET_KEY, GCP credentials, etc.)   │
└─────────────────────────────────────────────────────────────────┘
           ↑
           │ Reads
           │
┌──────────┴──────────────────────────────────────────────────────┐
│                          .env                                   │
│  • SECRET_KEY=your_secret_key                                   │
│  • GCP_PROJECT=your-project-id                                  │
│  • GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json            │
└─────────────────────────────────────────────────────────────────┘


┌─────────────────────────────────────────────────────────────────┐
│                    ADMIN SCRIPTS (Optional)                     │
├─────────────────────────────────────────────────────────────────┤
│  scripts/register_client.py  → Registers new clients           │
│  scripts/test_client.py      → Tests the server                │
└─────────────────────────────────────────────────────────────────┘

---

Step-by-Step Execution Flow

Flow 1: Server Startup

1. User runs: python -m src.server
   ↓
2. src/server.py main() is called
   ↓
3. Loads config from src/config.py
   ↓
4. config.py reads .env file
   ↓
5. Creates BigQueryMCPServer instance
   ↓
6. Initializes AuthenticationManager (src/auth.py)
   ↓
7. Initializes BigQueryClientManager (src/bigquery_client.py)
   ↓
8. Registers MCP tools (auth.authenticate, bq.run_query, etc.)
   ↓
9. Starts MCP server listening on stdio
   ↓
10. Server is ready to accept connections! 

Flow 2: Client Authentication

1. Client calls tool: auth.authenticate
   with client_id and client_secret
   ↓
2. server.py receives call
   ↓
3. Routes to _handle_authenticate()
   ↓
4. Calls auth_manager.authenticate()
   ↓
5. auth.py verifies credentials
   ↓
6. Generates JWT token
   ↓
7. Creates ClientSession
   ↓
8. Returns token to client 

Flow 3: Query Execution

1. Client calls tool: bq.run_query
   with token and SQL query
   ↓
2. server.py receives call
   ↓
3. Routes to _handle_run_query()
   ↓
4. Verifies token using auth_manager.verify_token()
   ↓
5. Gets BigQuery client from bq_manager
   ↓
6. Creates BigQueryOperations instance
   ↓
7. Executes query on BigQuery
   ↓
8. Returns results to client 

---

HOW TO RUN - COMPLETE GUIDE

Step 1: Prepare Environment

# Navigate to project directory
cd bigquery-mcp-server

# Create .env file
touch .env

Edit .env:

SECRET_KEY=PUT_YOUR_SECRET_KEY_HERE
TOKEN_TTL_HOURS=24
MAX_QUERY_RESULTS=10000
LOG_LEVEL=INFO

GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/service-account-key.json
GCP_PROJECT=your-gcp-project-id

Generate SECRET_KEY:

python -c "import secrets; print(secrets.token_urlsafe(32))"

---

Step 2: Install Dependencies

pip install -r requirements.txt

---

Step 3: Register a Client

# Generate new client credentials
python scripts/register_client.py \
    --project-id your-gcp-project-id \
    --datasets "*" \
    --generate

SAVE THE OUTPUT! It will show:

Client ID:     client_xxxxxxxxx
Client Secret: secret_yyyyyyyy

---

Step 4: Start the Server

# Run the server
python -m src.server

You should see:

2024-XX-XX XX:XX:XX - __main__ - INFO - Authentication manager initialized
2024-XX-XX XX:XX:XX - __main__ - INFO - BigQuery MCP Server initialized
2024-XX-XX XX:XX:XX - __main__ - INFO - Client registered: demo_client (project: my-project)
2024-XX-XX XX:XX:XX - __main__ - INFO - Starting BigQuery MCP Server...

---

Step 5: Test the Server (in new terminal)

# Open NEW terminal window
cd bigquery-mcp-server

# Run test client
python scripts/test_client.py client_xxxxxxxxx secret_yyyyyyyy

---

Which Files Connect to Which

File	Imports From	Used By	Purpose
src/config.py	.env, os, dotenv	All other files	Load configuration
src/auth.py	None	src/server.py	Authentication & sessions
src/bigquery_client.py	google.cloud.bigquery	src/server.py	BigQuery operations
src/server.py	config.py, auth.py, bigquery_client.py	Main entry point	MCP server logic
scripts/register_client.py	src/config.py, src/auth.py	Run manually	Register clients
scripts/test_client.py	mcp library	Run manually	Test server

---

Execution Order

Server Startup:

1. python -m src.server
2. → src/server.py: main()
3. → src/config.py: Config()
4. → .env: Load environment variables
5. → src/auth.py: AuthenticationManager()
6. → src/bigquery_client.py: BigQueryClientManager()
7. → Server starts listening

Client Test:

1. python scripts/test_client.py CLIENT_ID SECRET
2. → Starts new Python process for server
3. → test_client connects via MCP protocol
4. → Calls auth.authenticate tool
5. → Server routes to src/auth.py
6. → Returns token
7. → Calls bq.run_query tool
8. → Server routes to src/bigquery_client.py
9. → Executes query on BigQuery
10. → Returns results

---

Verification Checklist

• .env file created with all variables
• pip install -r requirements.txt completed
• Google Cloud credentials file exists
• Client registered successfully
• Server starts without errors
• Test client runs all 4 tests successfully

---

You're Done!

Your BigQuery MCP Server is now fully operational!