{"id":30209087,"url":"https://github.com/pvoo/bigquery-mcp","last_synced_at":"2026-04-11T07:36:54.075Z","repository":{"id":309614045,"uuid":"1033845509","full_name":"pvoo/bigquery-mcp","owner":"pvoo","description":"Practical MCP server for quickly navigating BigQuery datasets and tables. Suitable for larger projects with many datasets/tables, optimized to keep LLM context small while staying fast and safe.","archived":false,"fork":false,"pushed_at":"2025-08-12T20:39:15.000Z","size":157,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-12T22:24:22.277Z","etag":null,"topics":["bigquery","claude-code","cursor","fastmcp","mcp","mcp-server","mcp-servers","mcp-tools","windsurf"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pvoo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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-08-07T12:41:11.000Z","updated_at":"2025-08-12T20:41:40.000Z","dependencies_parsed_at":"2025-08-13T18:17:20.174Z","dependency_job_id":null,"html_url":"https://github.com/pvoo/bigquery-mcp","commit_stats":null,"previous_names":["pvoo/bigquery-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/pvoo/bigquery-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvoo%2Fbigquery-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvoo%2Fbigquery-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvoo%2Fbigquery-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvoo%2Fbigquery-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pvoo","download_url":"https://codeload.github.com/pvoo/bigquery-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvoo%2Fbigquery-mcp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270295329,"owners_count":24560344,"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","status":"online","status_checked_at":"2025-08-13T02:00:09.904Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["bigquery","claude-code","cursor","fastmcp","mcp","mcp-server","mcp-servers","mcp-tools","windsurf"],"created_at":"2025-08-13T19:01:13.993Z","updated_at":"2026-04-11T07:36:49.055Z","avatar_url":"https://github.com/pvoo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🗂️ BigQuery MCP Server\n\nPractical MCP server for navigating BigQuery datasets and tables by LLMs. Designed for larger projects with many datasets/tables, optimized to keep LLM context small while staying fast and safe.\n\n- **Minimal by default**: list datasets and tables names; fetch details only when asked\n- **Navigate larger projects**: filter by name, request detailed metadata/schemas on demand\n- **Quick table insight**: optional schema, column descriptions and fill-rate to help an agent decide relevance fast\n- **Safe to run**: read-only query execution with guardrails (SELECT/WITH only, comment stripping)\n\n## Quick Start\n\n**Prerequisites:** Python 3.10+ and [uv](https://github.com/astral-sh/uv) package manager\n\n### 🚀 Quick Setup\n\n**Option 1: Pull direct from GitHub**\n```bash\n# 1. Authenticate\ngcloud auth application-default login\n\n# 2. Run server\nuv run --with 'bigquery-mcp@git+https://github.com/pvoo/bigquery-mcp.git' \\\n  bigquery-mcp --project YOUR_PROJECT --location US\n```\n\n**Option 2: Clone locally (development setup)**\n```bash\n# 1. Clone and setup\ngit clone https://github.com/pvoo/bigquery-mcp.git\ncd bigquery-mcp\n\n# 2. Configure environment\ncp .env.example .env\n# Edit .env with your project and location\n\n# 3. Run or inspect\nmake run      # Start server\nmake inspect  # Open MCP inspector\n```\n\n\n### 🔧 MCP Client Configuration\n\n**Option 1: Basic MCP config**\nShould work as mcp.json config for most tools like Cursor, Claude Code, etc.\n```json\n{\n  \"mcpServers\": {\n    \"bigquery\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\", \"--with\", \"bigquery-mcp@git+https://github.com/pvoo/bigquery-mcp.git\",\n        \"bigquery-mcp\", \"--project\", \"your-project-id\", \"--location\", \"US\"\n      ]\n    }\n  }\n}\n```\n\n**Option 2: Local clone config (for development)**\n```bash\n# Clone first\ngit clone https://github.com/pvoo/bigquery-mcp.git\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"bigquery\": {\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"/absolute/path/to/bigquery-mcp\", \"run\", \"bigquery-mcp\"],\n      \"env\": {\n        \"GCP_PROJECT_ID\": \"your-project-id\",\n        \"BIGQUERY_LOCATION\": \"US\"\n      }\n    }\n  }\n}\n```\n\n### 🧪 Test Your Setup\n\n```bash\n# Test with MCP inspector\nnpx @modelcontextprotocol/inspector \\\n  uv run --with 'bigquery-mcp @ git+https://github.com/pvoo/bigquery-mcp.git' \\\n  bigquery-mcp --project YOUR_PROJECT --location US\n```\n\n## 🛠️ Tools Overview\n\nThis MCP server provides 4 core BigQuery tools optimized for LLM efficiency:\n\n### 📊 Smart Dataset \u0026 Table Discovery\n- **`list_datasets`** - Dual mode: basic (names only) vs detailed (full metadata)\n- **`list_tables`** - Context-aware table browsing with optional schema details\n- **`get_table`** - Complete table analysis with schema and sample data\n\n### 🔍 Safe Query Execution\n- **`run_query`** - Execute SELECT/WITH queries only, with cost tracking and safety validation\n\n**Key Features:**\n- ✅ **Minimal by default** - 70% fewer tokens in basic mode\n- ✅ **Safe queries only** - Blocks all write operations\n- ✅ **LLM-optimized** - Returns structured data perfect for AI analysis\n- ✅ **Cost transparent** - Shows bytes processed for each query\n\n## 🏗️ Development Setup\n\n### Local Development\n```bash\n# Clone and setup\ngit clone https://github.com/pvoo/bigquery-mcp.git\ncd bigquery-mcp\nmake install  # Setup environment + pre-commit hooks\n\n# Development workflow\nmake run      # Start server\nmake test     # Run test suite\nmake check    # Lint + format + typecheck\nmake inspect  # Launch MCP inspector\n```\n\n### Testing \u0026 Quality\n```bash\nmake test                    # Full test suite\npytest tests/test_safety.py  # SQL safety validation tests\npytest tests/test_server.py  # Core server functionality tests\nmake check                   # Run all quality checks\n```\n\n## Arguments available\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `GCP_PROJECT_ID` | Yes | Google Cloud project ID |\n| `BIGQUERY_LOCATION` | Yes | BigQuery region (e.g., US, EU, us-central1) |\n| `GOOGLE_APPLICATION_CREDENTIALS` | No | Path to service account JSON |\n| `BIGQUERY_MAX_RESULTS` | No | Default max query results (default: 20) |\n| `BIGQUERY_ALLOWED_DATASETS` | No | Comma-separated allowed datasets |\n\n**Authentication Methods:**\n1. **Application Default Credentials** (via `gcloud auth application-default login`)\n2. **Service Account Key** (set `GOOGLE_APPLICATION_CREDENTIALS`)\n\n**Required BigQuery Permissions:**\n`bigquery.datasets.get`, `bigquery.datasets.list`, `bigquery.tables.list`, `bigquery.tables.get`, `bigquery.jobs.create`, `bigquery.data.get`\n\n## 🚨 Troubleshooting\n\n**Authentication Issues:**\n```bash\n# Check current auth\ngcloud auth application-default print-access-token\n\n# Re-authenticate\ngcloud auth application-default login\n\n# Enable BigQuery API\ngcloud services enable bigquery.googleapis.com\n```\n\n**MCP Connection Issues:**\n- Ensure absolute paths in MCP config\n- Test server manually: `make run`\n- Check that project and location environment variables or args are set correctly\n\n**Performance Issues:**\n- Use `{\"detailed\": false}` for faster responses\n- Add search filters: `{\"search\": \"pattern\"}`\n- Reduce max_results for large datasets\n\n## 💡 Usage Examples\n\n### 📊 SQL Query Example\n```sql\n-- Query public datasets\nSELECT\n    EXTRACT(YEAR FROM pickup_datetime) as year,\n    COUNT(*) as trips,\n    ROUND(AVG(fare_amount), 2) as avg_fare\nFROM `bigquery-public-data.new_york_taxi_trips.tlc_yellow_trips_2020`\nWHERE pickup_datetime BETWEEN '2020-01-01' AND '2020-12-31'\nGROUP BY year\n```\n\n### 🤖 Example: Usage with Claude Code subagent\n\n**Scenario:** Use the specialized BigQuery Table Analyst agent in Claude Code to automatically explore your data warehouse, analyze table relationships, and provide structured insights. By using the subagent you can take the context used for analyzing the tables out of the main thread and return actionable insights into the main agent thread for writing SQL or analyzing.\n\n**Setup:**\n```bash\n# 1. Clone and configure\ngit clone https://github.com/pvoo/bigquery-mcp.git\ncd bigquery-mcp\n\n# 2. Setup environment\nexport GCP_PROJECT_ID=\"your-project-id\"\nexport BIGQUERY_LOCATION=\"US\"\ngcloud auth application-default login\n\n# 3. Launch Claude Code\nclaude-code\n```\n\n**Example Usage:**\n```\n💬 You: \"I need to understand our sales data structure and find tables related to customer orders\"\n\n🤖 Claude: I'll use the BigQuery Table Analyst agent to explore your sales datasets and identify relevant tables with their relationships.\n\n[Agent automatically:]\n- Lists all datasets to identify sales-related ones\n- Explores table schemas with detailed metadata\n- Shows actual sample data from key tables\n- Discovers join relationships between tables\n- Provides ready-to-use SQL queries\n```\n\n**What the Agent Returns:**\n- **Table schemas** with column descriptions and types\n- **Sample data** showing actual values (not placeholders)\n- **Join relationships** with working SQL examples\n- **Data quality insights** (null rates, freshness, etc.)\n- **Actionable SQL queries** you can immediately execute\n\n\n\n## 🤝 Contributing\n\nWe welcome contributions! Looking forward to your feedback for improvements.\n\n**Quick Start:**\n```bash\n# Fork on GitHub, then:\ngit clone https://github.com/yourusername/bigquery-mcp.git\ncd bigquery-mcp\nmake install  # Setup dev environment\nmake check    # Verify everything works\n\n# Make changes, then:\nmake test     # Run tests\nmake check    # Quality checks\n# Submit PR!\n```\n\n**Development Guidelines:**\n- Add tests for new features\n- Update documentation\n- Follow existing code style (enforced by pre-commit hooks)\n- Ensure all quality checks pass\n\n**Found an issue or have a feature request?**\n- 🐛 **Bug reports:** [Open an issue](https://github.com/pvoo/bigquery-mcp/issues)\n- 🔧 **Code improvements:** Submit a pull request\n- 📖 **Documentation:** See [CONTRIBUTING.md](CONTRIBUTING.md)\n\n---\n\n**🌟 Star this repo if it helps you!**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpvoo%2Fbigquery-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpvoo%2Fbigquery-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpvoo%2Fbigquery-mcp/lists"}