MCP BigQuery 服务器
一个安全的模型上下文协议（MCP）服务器，采用Python、FastMCP和Docker构建，通过承载令牌认证为AI助手提供访问Google BigQuery的权限。
🎯 概述
这个项目实现了一个MCP服务器，使得AI助手（如Claude）能够安全地与Google BigQuery数据集进行交互。该服务器采用Bearer Token认证方式，并使用Docker进行容器化，以便于部署。
✨ 特点
- 🔐（锁形符号，常用于表示密码、保密或安全） 安全认证API访问的Bearer令牌认证
- 🗄️（文件柜、文件夹） BigQuery 集成执行查询并探索数据集
- 🐳（海豚） 集装箱化的Docker就绪，实现一致部署
- ⚡（闪电符号，常用于表示速度、能量、快速或警示等含义，在中文中无直接对应词汇，通常保留原样或根据上下文意译） 现代工具使用uv包管理器构建，实现快速、可靠的构建过程
- 📊 表格/数据图表 MCP协议完整模型上下文协议合规性
🛠️ 技术栈
- 语言Python 3.11+（或：Python 3.11及以上版本）
- 包管理器： 紫外线
- MCP框架： FastMCP
- BigQuery 客户端： Google Cloud BigQuery v3.38.0+
- 集装箱Docker + Docker Compose
- 测试pytest
📁 项目结构
ProjectMCP/
├── src/mcp_bigquery/ # Main application code
│ ├── server.py # FastMCP server
│ ├── auth.py # Authentication middleware
│ ├── bigquery_client.py # BigQuery wrapper
│ └── config.py # Configuration
├── scripts/ # Utility scripts
│ └── generate_jwt_token.py # JWT token generator for testing
├── tests/ # Test suite
├── docs/ # Documentation
├── Dockerfile # Container definition
├── docker-compose.yml # Orchestration
├── pyproject.toml # Python dependencies
└── README.md # This file🚀 快速入门
先决条件
- Python 3.11或更高版本
- Docker Desktop（桌面版）
- 已启用BigQuery API的Google Cloud项目
- 具有BigQuery权限的服务账户
- UV包管理器
安装
# Install uv
pip install uv
# Clone repository
git clone
cd ProjectMCP
# Install dependencies
uv sync
# Set up environment
cp .env.example .env
# Edit .env with your credentials
# Run with Docker
docker-compose up📚 文档
- QUICKSTART.md 翻译为中文是：“快速入门指南.md” - 详细的入门指南
- tasks.md（文件名，可译为“任务列表.md”或保持原样，具体根据上下文决定是否翻译文件名） - 完整的实施任务清单
- projectbrief.md（项目简介文件） - 技术架构和需求
🔧 配置
服务器需要以下环境变量：
BEARER_TOKEN=your-secret-token-here
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
GCP_PROJECT_ID=your-gcp-project-id
LOG_LEVEL=INFO🎯 可用的MCP工具
一旦运行，服务器将提供以下MCP工具：
execute_query- 在BigQuery上执行SQL查询list_datasets- 列出所有可用的数据集list_tables- 列出数据集中的表格get_table_schema- 获取表模式信息
🧪 开发
# Run tests
uv run pytest
# Run with coverage
uv run pytest --cov=src/mcp_bigquery
# Format code
uv run black src/ tests/
# Type checking
uv run mypy src/
# Generate JWT tokens and save keys to files
uv run python scripts/generate_jwt_token.py --public-key-file public_key.pem --private-key-file private_key.pem --token-file token.txt
# View help for all options
uv run python scripts/generate_jwt_token.py --help📊 实施进度
看 tasks.md（文件名，可译为“任务列表.md”或保持原样，根据上下文决定是否需要具体翻译文件名） 用于详细进度跟踪。
当前状态🔴 规划阶段
阶段
- ⏳ 第一阶段：项目设置（0/2 完成）
- ⏳ 第二阶段：核心实施（0/4 完成）
- ⏳ 第三阶段：容器化（0/3 完成）
- ⏳ 第四阶段：测试（0/3完成）
- ⏳ 第五阶段：文档编制（0/3 完成）
- ⏳ 第六阶段：安全与质量（0/2 完成）
- ⏳ 第七阶段：发布（0/2 完成）
🔐 安全
- 承载令牌应为32个字符以上且随机生成
- 服务账户凭据绝不应提交到版本控制系统中
- 为BigQuery权限使用最小权限原则
- 所有认证尝试均被记录
- Docker 容器以非 root 用户身份运行
📝 许可证
\[在此添加您的许可证\]
🤝 贡献
欢迎投稿！请参阅 CONTRIBUTING.md（贡献指南文件） 作为指南。
📧 联系方式
\[添加您的联系方式\]
______________________________________________________________________
状态这个项目正处于规划/开发阶段。详见 tasks.md（文件名，可译为“任务说明文件”或保持原样不翻译，因为文件名通常不直接翻译，但根据上下文，“任务文件”也是一个合理的解释） 以了解当前进展。