{"id":22670765,"url":"https://github.com/ergut/mcp-bigquery-server","last_synced_at":"2025-05-07T02:21:04.834Z","repository":{"id":266349687,"uuid":"898108083","full_name":"ergut/mcp-bigquery-server","owner":"ergut","description":"A Model Context Protocol (MCP) server that provides secure, read-only access to BigQuery datasets. Enables Large Language Models (LLMs) to safely query and analyze data through a standardized interface.","archived":false,"fork":false,"pushed_at":"2025-04-03T12:35:20.000Z","size":283,"stargazers_count":46,"open_issues_count":6,"forks_count":12,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-12T08:14:22.245Z","etag":null,"topics":["bigquery","google-cloud","mcp","mcp-servers","model-context-protocol","sql"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/ergut.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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}},"created_at":"2024-12-03T19:57:59.000Z","updated_at":"2025-04-11T13:41:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"89569f0e-c2c1-4cf8-9361-0f82fa5e1dab","html_url":"https://github.com/ergut/mcp-bigquery-server","commit_stats":null,"previous_names":["ergut/mcp-bigquery-server"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ergut%2Fmcp-bigquery-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ergut%2Fmcp-bigquery-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ergut%2Fmcp-bigquery-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ergut%2Fmcp-bigquery-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ergut","download_url":"https://codeload.github.com/ergut/mcp-bigquery-server/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252799159,"owners_count":21805950,"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":["bigquery","google-cloud","mcp","mcp-servers","model-context-protocol","sql"],"created_at":"2024-12-09T16:01:14.271Z","updated_at":"2025-05-07T02:21:04.824Z","avatar_url":"https://github.com/ergut.png","language":"JavaScript","readme":"# BigQuery MCP Server\n[![smithery badge](https://smithery.ai/badge/@ergut/mcp-bigquery-server)](https://smithery.ai/protocol/@ergut/mcp-bigquery-server)\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/mcp-bigquery-server-logo.png\" alt=\"BigQuery MCP Server Logo\" width=\"400\"/\u003e\n\u003c/div\u003e\n\n## What is this? 🤔\n\nThis is a server that lets your LLMs (like Claude) talk directly to your BigQuery data! Think of it as a friendly translator that sits between your AI assistant and your database, making sure they can chat securely and efficiently.\n\n### Quick Example\n```text\nYou: \"What were our top 10 customers last month?\"\nClaude: *queries your BigQuery database and gives you the answer in plain English*\n```\n\nNo more writing SQL queries by hand - just chat naturally with your data!\n\n## How Does It Work? 🛠️\n\nThis server uses the Model Context Protocol (MCP), which is like a universal translator for AI-database communication. While MCP is designed to work with any AI model, right now it's available as a developer preview in Claude Desktop.\n\nHere's all you need to do:\n1. Set up authentication (see below)\n2. Add your project details to Claude Desktop's config file\n3. Start chatting with your BigQuery data naturally!\n\n### What Can It Do? 📊\n\n- Run SQL queries by just asking questions in plain English\n- Access both tables and materialized views in your datasets\n- Explore dataset schemas with clear labeling of resource types (tables vs views)\n- Analyze data within safe limits (1GB query limit by default)\n- Keep your data secure (read-only access)\n\n## Quick Start 🚀\n\n### Prerequisites\n- Node.js 14 or higher\n- Google Cloud project with BigQuery enabled\n- Either Google Cloud CLI installed or a service account key file\n- Claude Desktop (currently the only supported LLM interface)\n\n### Option 1: Quick Install via Smithery (Recommended)\nTo install BigQuery MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/protocol/@ergut/mcp-bigquery-server), run this command in your terminal:\n\n```bash\nnpx @smithery/cli install @ergut/mcp-bigquery-server --client claude\n```\nThe installer will prompt you for:\n\n- Your Google Cloud project ID\n- BigQuery location (defaults to us-central1)\n\nOnce configured, Smithery will automatically update your Claude Desktop configuration and restart the application.\n\n### Option 2: Manual Setup\nIf you prefer manual configuration or need more control:\n\n1. **Authenticate with Google Cloud** (choose one method):\n   - Using Google Cloud CLI (great for development):\n     ```bash\n     gcloud auth application-default login\n     ```\n   - Using a service account (recommended for production):\n     ```bash\n     # Save your service account key file and use --key-file parameter\n     # Remember to keep your service account key file secure and never commit it to version control\n     ```\n\n2. **Add to your Claude Desktop config**\n   Add this to your `claude_desktop_config.json`:\n\n   - Basic configuration:\n     ```json\n     {\n       \"mcpServers\": {\n         \"bigquery\": {\n           \"command\": \"npx\",\n           \"args\": [\n             \"-y\",\n             \"@ergut/mcp-bigquery-server\",\n             \"--project-id\",\n             \"your-project-id\",\n             \"--location\",\n             \"us-central1\"\n           ]\n         }\n       }\n     }\n     ```\n\n   - With service account:\n     ```json\n     {\n       \"mcpServers\": {\n         \"bigquery\": {\n           \"command\": \"npx\",\n           \"args\": [\n             \"-y\",\n             \"@ergut/mcp-bigquery-server\",\n             \"--project-id\",\n             \"your-project-id\",\n             \"--location\",\n             \"us-central1\",\n             \"--key-file\",\n             \"/path/to/service-account-key.json\"\n           ]\n         }\n       }\n     }\n     ```\n     \n\n3. **Start chatting!** \n   Open Claude Desktop and start asking questions about your data.\n\n### Command Line Arguments\n\nThe server accepts the following arguments:\n- `--project-id`: (Required) Your Google Cloud project ID\n- `--location`: (Optional) BigQuery location, defaults to 'us-central1'\n- `--key-file`: (Optional) Path to service account key JSON file\n\nExample using service account:\n```bash\nnpx @ergut/mcp-bigquery-server --project-id your-project-id --location europe-west1 --key-file /path/to/key.json\n```\n\n### Permissions Needed\n\nYou'll need one of these:\n- `roles/bigquery.user` (recommended)\n- OR both:\n  - `roles/bigquery.dataViewer`\n  - `roles/bigquery.jobUser`\n\n## Developer Setup (Optional) 🔧\n\nWant to customize or contribute? Here's how to set it up locally:\n\n```bash\n# Clone and install\ngit clone https://github.com/ergut/mcp-bigquery-server\ncd mcp-bigquery-server\nnpm install\n\n# Build\nnpm run build\n```\n\nThen update your Claude Desktop config to point to your local build:\n```json\n{\n  \"mcpServers\": {\n    \"bigquery\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/path/to/your/clone/mcp-bigquery-server/dist/index.js\",\n        \"--project-id\",\n        \"your-project-id\",\n        \"--location\",\n        \"us-central1\",\n        \"--key-file\",\n        \"/path/to/service-account-key.json\"\n      ]\n    }\n  }\n}\n```\n\n## Current Limitations ⚠️\n\n- MCP support is currently only available in Claude Desktop (developer preview)\n- Connections are limited to local MCP servers running on the same machine\n- Queries are read-only with a 1GB processing limit\n- While both tables and views are supported, some complex view types might have limitations\n\n## Support \u0026 Resources 💬\n\n- 🐛 [Report issues](https://github.com/ergut/mcp-bigquery-server/issues)\n- 💡 [Feature requests](https://github.com/ergut/mcp-bigquery-server/issues)\n- 📖 [Documentation](https://github.com/ergut/mcp-bigquery-server)\n\n## License 📝\n\nMIT License - See [LICENSE](LICENSE) file for details.\n\n## Author ✍️ \n\nSalih Ergüt\n\n## Sponsorship\n\nThis project is proudly sponsored by:\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://www.oredata.com\"\u003e\n    \u003cimg src=\"assets/oredata-logo-nobg.png\" alt=\"OREDATA\" width=\"300\"/\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n## Version History 📋\n\nSee [CHANGELOG.md](CHANGELOG.md) for updates and version history.","funding_links":[],"categories":["Databases","Database \u0026 Messaging MCP Servers","サーバー実装","📚 Projects (1974 total)","🗄️ \u003ca name=\"databases\"\u003e\u003c/a\u003eDatabases","Community Servers","MCP 服务器精选列表","Legend","🗄️ Database","Cloud Services","MCP Servers","Table of Contents","Uncategorized","🗂️ Extensions by Category","JavaScript"],"sub_categories":["Analytics \u0026 Warehouses","🗄️ \u003ca name=\"databases\"\u003e\u003c/a\u003eデータベース","MCP Servers","🗄️ 数据库交互","🗄️ \u003ca name=\"databases\"\u003e\u003c/a\u003eDatabases","🧮 \u003ca name=\"data-science-tools\"\u003e\u003c/a\u003eデータサイエンスツール","How to Submit","🗄️ Databases","💾 Databases","AI Services","Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fergut%2Fmcp-bigquery-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fergut%2Fmcp-bigquery-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fergut%2Fmcp-bigquery-server/lists"}