iflow-mcp_mcp-server-bigquery 0.3.1__py3-none-any.whl

iflow_mcp_mcp_server_bigquery-0.3.1.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: iflow-mcp_mcp-server-bigquery
+Version: 0.3.1
+Summary: A Model Context Protocol server that provides access to BigQuery. This server enables LLMs to inspect database schemas and execute queries.
+Author: Lucas Hild
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: google-cloud-bigquery>=3.27.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# BigQuery MCP server
+
+[![smithery badge](https://smithery.ai/badge/mcp-server-bigquery)](https://smithery.ai/server/mcp-server-bigquery)
+
+A Model Context Protocol server that provides access to BigQuery. This server enables LLMs to inspect database schemas and execute queries.
+
+## Components
+
+### Tools
+
+The server implements one tool:
+
+- `execute-query`: Executes a SQL query using BigQuery dialect
+- `list-tables`: Lists all tables in the BigQuery database
+- `describe-table`: Describes the schema of a specific table
+
+## Configuration
+
+The server can be configured either with command line arguments or environment variables.
+
+| Argument     | Environment Variable | Required | Description                                                                                                                                                                                                                                                                                                                                                    |
+| ------------ | -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--project`  | `BIGQUERY_PROJECT`   | Yes      | The GCP project ID.                                                                                                                                                                                                                                                                                                                                            |
+| `--location` | `BIGQUERY_LOCATION`  | Yes      | The GCP location (e.g. `europe-west9`).                                                                                                                                                                                                                                                                                                                        |
+| `--dataset`  | `BIGQUERY_DATASETS`  | No       | Only take specific BigQuery datasets into consideration. Several datasets can be specified by repeating the argument (e.g. `--dataset my_dataset_1 --dataset my_dataset_2`) or by joining them with a comma in the environment variable (e.g. `BIGQUERY_DATASETS=my_dataset_1,my_dataset_2`). If not provided, all datasets in the project will be considered. |
+| `--key-file` | `BIGQUERY_KEY_FILE`  | No       | Path to a service account key file for BigQuery. If not provided, the server will use the default credentials.                                                                                                                                                                                                                                                 |
+
+## Quickstart
+
+### Install
+
+#### Installing via Smithery
+
+To install BigQuery Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-server-bigquery):
+
+```bash
+npx -y @smithery/cli install mcp-server-bigquery --client claude
+```
+
+#### Claude Desktop
+
+On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
+On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
+
+##### Development/Unpublished Servers Configuration</summary>
+
+```json
+"mcpServers": {
+  "bigquery": {
+    "command": "uv",
+    "args": [
+      "--directory",
+      "{{PATH_TO_REPO}}",
+      "run",
+      "mcp-server-bigquery",
+      "--project",
+      "{{GCP_PROJECT_ID}}",
+      "--location",
+      "{{GCP_LOCATION}}"
+    ]
+  }
+}
+```
+
+##### Published Servers Configuration
+
+```json
+"mcpServers": {
+  "bigquery": {
+    "command": "uvx",
+    "args": [
+      "mcp-server-bigquery",
+      "--project",
+      "{{GCP_PROJECT_ID}}",
+      "--location",
+      "{{GCP_LOCATION}}"
+    ]
+  }
+}
+```
+
+Replace `{{PATH_TO_REPO}}`, `{{GCP_PROJECT_ID}}`, and `{{GCP_LOCATION}}` with the appropriate values.
+
+## Development
+
+### Building and Publishing
+
+To prepare the package for distribution:
+
+1. Increase the version number in `pyproject.toml`
+
+2. Sync dependencies and update lockfile:
+
+```bash
+uv sync
+```
+
+3. Build package distributions:
+
+```bash
+uv build
+```
+
+This will create source and wheel distributions in the `dist/` directory.
+
+4. Publish to PyPI:
+
+```bash
+uv publish
+```
+
+Note: You'll need to set PyPI credentials via environment variables or command flags:
+
+- Token: `--token` or `UV_PUBLISH_TOKEN`
+- Or username/password: `--username`/`UV_PUBLISH_USERNAME` and `--password`/`UV_PUBLISH_PASSWORD`
+
+### Debugging
+
+Since MCP servers run over stdio, debugging can be challenging. For the best debugging
+experience, we strongly recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
+
+You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:
+
+```bash
+npx @modelcontextprotocol/inspector uv --directory {{PATH_TO_REPO}} run mcp-server-bigquery
+```
+
+Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

iflow_mcp_mcp_server_bigquery-0.3.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+mcp_server_bigquery/__init__.py,sha256=X1ta3m-alGK-SkOzY-wUxkFXFYsYWGaEiaBYymbdRBc,1295
+mcp_server_bigquery/server.py,sha256=MzeLE4EgUrB8fY1zIEO973LaItaR-x2ZNCESidXvexk,7646
+iflow_mcp_mcp_server_bigquery-0.3.1.dist-info/METADATA,sha256=OauDyIYiVMRiarJ_08a5nTD9EkwM7gJ3kMt6kOblQMo,5728
+iflow_mcp_mcp_server_bigquery-0.3.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+iflow_mcp_mcp_server_bigquery-0.3.1.dist-info/entry_points.txt,sha256=cgwDx4ywZKfn6NKgfs_R27BLCJ4OLfiVOGDLnCmDAr0,65
+iflow_mcp_mcp_server_bigquery-0.3.1.dist-info/licenses/LICENSE,sha256=Fwuj73c22MmMmJq8VG2FmoeIr5KSGDF5ePWjLXGWflk,1067
+iflow_mcp_mcp_server_bigquery-0.3.1.dist-info/RECORD,,

iflow_mcp_mcp_server_bigquery-0.3.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

iflow_mcp_mcp_server_bigquery-0.3.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-server-bigquery = mcp_server_bigquery:main

iflow_mcp_mcp_server_bigquery-0.3.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Lucas Hild
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_server_bigquery/__init__.py

@@ -0,0 +1,30 @@
+from . import server
+import asyncio
+import argparse
+import os
+
+
+def main():
+    """Main entry point for the package."""
+    parser = argparse.ArgumentParser(description='BigQuery MCP Server')
+    parser.add_argument('--project', help='BigQuery project', required=False)
+    parser.add_argument('--location', help='BigQuery location', required=False)
+    parser.add_argument('--key-file', help='BigQuery Service Account', required=False)
+    parser.add_argument('--dataset', help='BigQuery dataset', required=False, action='append')
+    
+    args = parser.parse_args()
+
+    # Get values from environment variables if not provided as arguments
+    project = args.project or os.environ.get('BIGQUERY_PROJECT')
+    location = args.location or os.environ.get('BIGQUERY_LOCATION')
+    key_file = args.key_file or os.environ.get('BIGQUERY_KEY_FILE')
+    
+    datasets_filter = args.dataset if args.dataset else []
+    if not datasets_filter and 'BIGQUERY_DATASETS' in os.environ:
+        datasets_filter = os.environ.get('BIGQUERY_DATASETS', '').split(',')
+        datasets_filter = [d.strip() for d in datasets_filter if d.strip()]
+    
+    asyncio.run(server.main(project, location, key_file, datasets_filter))
+
+# Optionally expose other important items at package level
+__all__ = ['main', 'server']

mcp_server_bigquery/server.py

@@ -0,0 +1,196 @@
+from google.cloud import bigquery
+from google.oauth2 import service_account
+import logging
+from mcp.server.models import InitializationOptions
+import mcp.types as types
+from mcp.server import NotificationOptions, Server
+import mcp.server.stdio
+from typing import Any, Optional
+
+# Set up logging to both stdout and file
+logger = logging.getLogger('mcp_bigquery_server')
+handler_stdout = logging.StreamHandler()
+handler_file = logging.FileHandler('/tmp/mcp_bigquery_server.log')
+
+# Set format for both handlers
+formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+handler_stdout.setFormatter(formatter)
+handler_file.setFormatter(formatter)
+
+# Add both handlers to logger
+logger.addHandler(handler_stdout)
+logger.addHandler(handler_file)
+
+# Set overall logging level
+logger.setLevel(logging.DEBUG)
+
+logger.info("Starting MCP BigQuery Server")
+
+class BigQueryDatabase:
+    def __init__(self, project: str, location: str, key_file: Optional[str], datasets_filter: list[str]):
+        """Initialize a BigQuery database client"""
+        logger.info(f"Initializing BigQuery client for project: {project}, location: {location}, key_file: {key_file}")
+        if not project:
+            raise ValueError("Project is required")
+        if not location:
+            raise ValueError("Location is required")
+        
+        credentials: service_account.Credentials | None = None
+        if key_file:
+            try:
+                credentials_path = key_file
+                credentials = service_account.Credentials.from_service_account_file(
+                    credentials_path,
+                    scopes=["https://www.googleapis.com/auth/cloud-platform"],
+                )
+            except Exception as e:
+                logger.error(f"Error loading service account credentials: {e}")
+                raise ValueError(f"Invalid key file: {e}")
+
+        self.client = bigquery.Client(credentials=credentials, project=project, location=location)
+        self.datasets_filter = datasets_filter
+
+    def execute_query(self, query: str, params: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+        """Execute a SQL query and return results as a list of dictionaries"""
+        logger.debug(f"Executing query: {query}")
+        try:
+            if params:
+                job = self.client.query(query, job_config=bigquery.QueryJobConfig(query_parameters=params))
+            else:
+                job = self.client.query(query)
+                
+            results = job.result()
+            rows = [dict(row.items()) for row in results]
+            logger.debug(f"Query returned {len(rows)} rows")
+            return rows
+        except Exception as e:
+            logger.error(f"Database error executing query: {e}")
+            raise
+    
+    def list_tables(self) -> list[str]:
+        """List all tables in the BigQuery database"""
+        logger.debug("Listing all tables")
+
+        if self.datasets_filter:
+            datasets = [self.client.dataset(dataset) for dataset in self.datasets_filter]
+        else:
+            datasets = list(self.client.list_datasets())
+
+        logger.debug(f"Found {len(datasets)} datasets")
+
+        tables = []
+        for dataset in datasets:
+            dataset_tables = self.client.list_tables(dataset.dataset_id)
+            tables.extend([
+                f"{dataset.dataset_id}.{table.table_id}" for table in dataset_tables
+            ])
+
+        logger.debug(f"Found {len(tables)} tables")
+        return tables
+
+    def describe_table(self, table_name: str) -> list[dict[str, Any]]:
+        """Describe a table in the BigQuery database"""
+        logger.debug(f"Describing table: {table_name}")
+
+        parts = table_name.split(".")
+        if len(parts) != 2 and len(parts) != 3:
+            raise ValueError(f"Invalid table name: {table_name}")
+
+        dataset_id = ".".join(parts[:-1])
+        table_id = parts[-1]
+
+        query = f"""
+            SELECT ddl
+            FROM {dataset_id}.INFORMATION_SCHEMA.TABLES
+            WHERE table_name = @table_name;
+        """
+        return self.execute_query(query, params=[
+            bigquery.ScalarQueryParameter("table_name", "STRING", table_id),
+        ])
+
+async def main(project: str, location: str, key_file: Optional[str], datasets_filter: list[str]):
+    logger.info(f"Starting BigQuery MCP Server with project: {project} and location: {location}")
+
+    db = BigQueryDatabase(project, location, key_file, datasets_filter)
+    server = Server("bigquery-manager")
+
+    # Register handlers
+    logger.debug("Registering handlers")
+
+    @server.list_tools()
+    async def handle_list_tools() -> list[types.Tool]:
+        """List available tools"""
+        return [
+            types.Tool(
+                name="execute-query",
+                description="Execute a SELECT query on the BigQuery database",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "query": {"type": "string", "description": "SELECT SQL query to execute using BigQuery dialect"},
+                    },
+                    "required": ["query"],
+                },
+            ),
+            types.Tool(
+                name="list-tables",
+                description="List all tables in the BigQuery database",
+                inputSchema={
+                    "type": "object",
+                    "properties": {},
+                },
+            ),
+            types.Tool(
+                name="describe-table",
+                description="Get the schema information for a specific table",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "table_name": {"type": "string", "description": "Name of the table to describe (e.g. my_dataset.my_table)"},
+                    },
+                    "required": ["table_name"],
+                },
+            ),
+        ]
+
+    @server.call_tool()
+    async def handle_call_tool(
+        name: str, arguments: dict[str, Any] | None
+    ) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
+        """Handle tool execution requests"""
+        logger.debug(f"Handling tool execution request: {name}")
+
+        try:
+            if name == "list-tables":
+                results = db.list_tables()
+                return [types.TextContent(type="text", text=str(results))]
+
+            elif name == "describe-table":
+                if not arguments or "table_name" not in arguments:
+                    raise ValueError("Missing table_name argument")
+                results = db.describe_table(arguments["table_name"])
+                return [types.TextContent(type="text", text=str(results))]
+
+            if name == "execute-query":
+                results = db.execute_query(arguments["query"])
+                return [types.TextContent(type="text", text=str(results))]
+
+            else:
+                raise ValueError(f"Unknown tool: {name}")
+        except Exception as e:
+            return [types.TextContent(type="text", text=f"Error: {str(e)}")]
+
+    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
+        logger.info("Server running with stdio transport")
+        await server.run(
+            read_stream,
+            write_stream,
+            InitializationOptions(
+                server_name="bigquery",
+                server_version="0.3.0",
+                capabilities=server.get_capabilities(
+                    notification_options=NotificationOptions(),
+                    experimental_capabilities={},
+                ),
+            ),
+        )