# lucashild/mcp-server-bigquery architecture

> Architecture diagram of the GitHub repository lucashild/mcp-server-bigquery, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucashild/mcp-server-bigquery
- Repository: https://github.com/lucashild/mcp-server-bigquery

## Overview

##### Project Type and Purpose
- This is a server-side application that bridges LLMs (language models) with BigQuery by providing tools to execute SQL queries, list tables, and describe table schemas.
- The primary goal is to allow LLMs to inspect database schemas and run BigQuery queries via a protocol (MCP) over standard I/O.

##### Analyzing the File Structure
- Notice that there is a single main package (located under src/mcp_server_bigquery) with a server.py file. This indicates that the core logic (handling incoming commands and interfacing with BigQuery) is encapsulated here.
- The presence of configuration files (e.g., pyproject.toml and uv.lock) suggests that the project is built using modern Python dependency management and build tooling.
- The simple structure reflects a focused responsibility: handling requests for BigQuery operations.

##### Key Components
a. MCP Server Component:
- Command parser (for processing requests like ‘execute-query’, ‘list-tables’, and ‘describe-table’).
- Business logic that handles forming and executing BigQuery requests.
- Output handler via stdio for communication with the client.
b. BigQuery Interaction:
- Execution of SQL queries.
- Retrieval of metadata (table lists and column descriptions).
c. Configuration & Deployment:
d. Client Tools & Debugging:
- That commands can be launched via the Smithery CLI and illustrated via provided configurations for Claude Desktop.

##### Architectural Patterns and Design Principles
- Service Oriented: The server is essentially a single-purpose service that exposes defined tools.
- Decoupling: The server logic is separated from the BigQuery integration, making it easier to test and debug.
- Protocol Driven: The use of MCP over stdio demonstrates a protocol-based communication, which should be distinctly noted.
- Extensibility: Although the project currently implements three tools (execute-query, list-tables, describe-table), the design can support additional functionalities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Tools & Debugging
    subgraph "Client Tools & Debugging"
        client("MCP Inspector / Smithery CLI"):::client
    end

    %% Core Application
    subgraph "Core Application"
        corePkg("Core Package Structure"):::code
        ms("BigQuery MCP Server"):::server
        cmdParser("Command Parser"):::subComp
        business("SQL Executor/Business Logic"):::subComp
        output("Output Handler (stdio)"):::subComp
        configManager("Configuration Manager"):::subComp
        
        corePkg --> ms
        ms --> cmdParser
        ms --> business
        ms --> output
        ms --> configManager
    end

    %% External Systems
    subgraph "External Systems"
        bq("BigQuery"):::external
    end

    %% Configuration & Deployment
    subgraph "Configuration & Deployment"
        runtime("Runtime Parameters (GCP Project, etc)"):::deploy
        buildTools("Build & Deployment Tools"):::deploy
    end

    %% Connections between components
    client -->|"MCPCommand"| ms
    business -->|"SQLQueryRequest"| bq
    bq -->|"QueryResponse"| business
    output -->|"ResponseviaStdio"| client
    runtime -->|"ProvidesConfig"| configManager

    %% Click Events
    click ms "https://github.com/lucashild/mcp-server-bigquery/blob/main/src/mcp_server_bigquery/server.py"
    click business "https://github.com/lucashild/mcp-server-bigquery/blob/main/src/mcp_server_bigquery/server.py"
    click configManager "https://github.com/lucashild/mcp-server-bigquery/blob/main/src/mcp_server_bigquery/server.py"
    click buildTools "https://github.com/lucashild/mcp-server-bigquery/blob/main/pyproject.toml"
    click buildTools "https://github.com/lucashild/mcp-server-bigquery/blob/main/uv.lock"
    click corePkg "https://github.com/lucashild/mcp-server-bigquery/tree/main/src/mcp_server_bigquery"

    %% Styles
    classDef server fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef subComp fill:#ccffcc,stroke:#333,stroke-width:1px;
    classDef client fill:#99ccff,stroke:#333,stroke-width:2px;
    classDef external fill:#ff9999,stroke:#333,stroke-width:2px;
    classDef deploy fill:#ccccff,stroke:#333,stroke-width:2px;
    classDef code fill:#ffe6cc,stroke:#333,stroke-width:1px;
```
