{"id":29154983,"url":"https://github.com/haginot/bigquery-mcp","last_synced_at":"2025-07-01T02:35:50.382Z","repository":{"id":288701091,"uuid":"968933982","full_name":"haginot/bigquery-mcp","owner":"haginot","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-19T06:22:21.000Z","size":78,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-19T11:50:45.844Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/haginot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-19T02:46:36.000Z","updated_at":"2025-04-19T03:37:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"465e4fed-fcd8-40aa-a281-a91b081afe5e","html_url":"https://github.com/haginot/bigquery-mcp","commit_stats":null,"previous_names":["haginot/bigquery-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/haginot/bigquery-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haginot%2Fbigquery-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haginot%2Fbigquery-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haginot%2Fbigquery-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haginot%2Fbigquery-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/haginot","download_url":"https://codeload.github.com/haginot/bigquery-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haginot%2Fbigquery-mcp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262884621,"owners_count":23379415,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-01T02:34:27.947Z","updated_at":"2025-07-01T02:35:50.363Z","avatar_url":"https://github.com/haginot.png","language":null,"readme":"# BigQuery MCP Server\n\nA fully-compliant Model Context Protocol (MCP) server that surfaces Google BigQuery functionality to LLM agents and other MCP clients. Implements MCP specification rev 2025-03-26.\n\n## Features\n\n- Implements MCP specification rev 2025-03-26\n- Supports stdio transport (default) and optional HTTP transport\n- Exposes BigQuery operations through MCP Tools\n- Includes direct stdio implementation optimized for Claude Desktop\n- Supports pagination for long result sets\n- Implements logging utilities\n- Handles errors according to JSON-RPC standards\n- Supports environment variable configuration for project ID and location\n- Optimized INFORMATION_SCHEMA query handling\n- Docker support for easy deployment\n\n## Installation\n\n```bash\n# Install from source\ngit clone https://github.com/haginot/bigquery-mcp.git\ncd bigquery-mcp\npip install .\n\n# Or using Poetry\npoetry install\n```\n\n## Authentication\n\nThe server uses Google Cloud authentication. You need to set up authentication credentials:\n\n```bash\n# Set the environment variable to your service account key file\nexport GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/service-account-key.json\n\n# Or use gcloud to authenticate\ngcloud auth application-default login\n```\n\n## Usage\n\n### Command Line\n\n```bash\n# Start with stdio transport (default)\nmcp-bigquery-server\n\n# Start with HTTP transport\nmcp-bigquery-server --http --port 8000\n\n# Enable resource exposure\nmcp-bigquery-server --expose-resources\n\n# Set query timeout\nmcp-bigquery-server --query-timeout-ms 60000\n```\n\n### Python API\n\n```python\nfrom mcp_bigquery_server.server import BigQueryMCPServer\n\n# Create and start the server\nserver = BigQueryMCPServer(\n    expose_resources=True,\n    http_enabled=True,\n    host=\"localhost\",\n    port=8000,\n    query_timeout_ms=30000,\n)\nserver.start()\n```\n\n### Docker\n\nYou can run the MCP server in a Docker container:\n\n```bash\n# Build the Docker image\ndocker build -t mcp-bigquery-server .\n\n# Run with stdio transport (for use with Claude Desktop)\ndocker run -i --rm \\\n  -v /path/to/credentials:/credentials \\\n  -e GOOGLE_APPLICATION_CREDENTIALS=/credentials/service-account-key.json \\\n  -e PROJECT_ID=your-project-id \\\n  -e LOCATION=US \\\n  mcp-bigquery-server --stdio\n\n# Run with HTTP transport\ndocker run -p 8000:8000 --rm \\\n  -v /path/to/credentials:/credentials \\\n  -e GOOGLE_APPLICATION_CREDENTIALS=/credentials/service-account-key.json \\\n  -e PROJECT_ID=your-project-id \\\n  -e LOCATION=US \\\n  mcp-bigquery-server\n```\n\nYou can also use docker-compose:\n\n```bash\n# Create a credentials directory and copy your service account key\nmkdir -p credentials\ncp /path/to/your/service-account-key.json credentials/service-account-key.json\n\n# Start the HTTP server with docker-compose\ndocker-compose up\n\n# Start the stdio server with docker-compose (for Claude Desktop)\ndocker-compose up mcp-bigquery-server-stdio\n```\n\n### Using with Claude Desktop\n\nTo use this MCP server with Claude Desktop:\n\n1. Run the server with stdio transport:\n   ```bash\n   # Using Docker directly\n   docker run -i --rm \\\n     -v /path/to/credentials:/credentials \\\n     -e GOOGLE_APPLICATION_CREDENTIALS=/credentials/service-account-key.json \\\n     -e PROJECT_ID=your-project-id \\\n     -e LOCATION=US \\\n     mcp-bigquery-server --stdio\n   \n   # Or using docker-compose (recommended)\n   docker-compose up mcp-bigquery-server-stdio\n   ```\n\n2. In Claude Desktop:\n   - Go to Settings \u003e Tools\n   - Select \"Add Tool\" \u003e \"Add MCP Tool\"\n   - Choose \"Connect to running MCP server\"\n   - Select \"stdio\" as the transport\n   - Click \"Connect\" and select the terminal running your Docker container\n\nClaude will now have access to all BigQuery operations through the MCP server.\n\n\n## Available Tools\n\nThe server exposes the following BigQuery operations as MCP tools:\n\n- `execute_query`: Submit a SQL query to BigQuery, optionally as dry-run\n- `execute_query_with_results`: Submit a SQL query to BigQuery and return results immediately\n- `get_job_status`: Poll job execution state\n- `cancel_job`: Cancel a running BigQuery job\n- `fetch_results_chunk`: Page through results\n- `list_datasets`: Enumerate datasets visible to the service account\n- `get_table_schema`: Retrieve schema for a table\n\n## Resources (Optional)\n\nWhen enabled with `--expose-resources`, the server exposes:\n\n- Dataset \u0026 table schemas as read-only resources (`bq://\u003cproject\u003e/\u003cdataset\u003e/schema`)\n- Query result sets (chunk URIs)\n\n## License\n\nMIT\n","funding_links":[],"categories":["Database \u0026 Messaging MCP Servers"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaginot%2Fbigquery-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhaginot%2Fbigquery-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaginot%2Fbigquery-mcp/lists"}