🚀 TNTM Google表格分析MCP服务器
TNTM打造的一款简洁实用的MCP(模型上下文协议)服务器,支持多标签,可用于分析Google表格数据。该服务器专为Claude Desktop及其他兼容MCP的AI助手而设计。
🚀 快速开始
TNTM Google表格分析MCP服务器是一款强大的工具,用于分析Google表格数据。以下是使用该服务器的基本步骤:
- 确保满足所有先决条件。
- 按照设置步骤进行安装和配置。
- 重启MCP客户端(如Claude Desktop),首次使用工具时将自动启动OAuth流程。
✨ 主要特性
- 智能同步:同步Google表格时可配置行限制,防止超时。
- 多标签支持:可使用SQL JOIN跨多个工作表进行查询。
- SQL查询:可直接对同步的数据进行SQL查询。
- 表格分析:提供跨工作表查询的建议。
- 快速预览:无需完全同步即可预览工作表。
- 性能优化:针对大型数据集设置行限制和结果分页。
📦 安装指南
1. 克隆并安装
git clone https://github.com/yourusername/google-sheet-analytics-mcp.git
cd google-sheet-analytics-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
2. Google Cloud设置
- 访问 Google Cloud控制台。
- 创建一个新项目或选择现有项目。
- 启用Google表格API。
- 创建OAuth2凭据(桌面应用程序)。
- 下载凭据并保存为项目根目录下的
credentials.json
。
3. 运行自动设置
python3 setup.py
这将:
- 设置OAuth身份验证。
- 自动配置Claude Desktop。
- 测试连接。
或者手动配置MCP客户端:
{
"mcpServers": {
"google-sheets-analytics": {
"command": "/path/to/your/venv/bin/python",
"args": ["/path/to/google-sheet-analytics-mcp/src/mcp_server.py"]
}
}
}
4. 首次运行
重启MCP客户端(如Claude Desktop),首次使用工具时将自动启动OAuth流程。
💻 使用示例
基础用法
多标签分析
SELECT
s.product_name,
s.sales_amount,
c.customer_name,
c.customer_segment
FROM sales_data s
JOIN customer_data c ON s.customer_id = c.id
WHERE s.sales_amount > 1000
跨工作表聚合
SELECT
region,
SUM(amount) as total_revenue
FROM (
SELECT region, amount FROM q1_sales
UNION ALL
SELECT region, amount FROM q2_sales
)
GROUP BY region
ORDER BY total_revenue DESC
高级用法
smart_sync
同步Google表格数据并进行性能控制。
使用 smart_sync,指定URL "https://docs.google.com/spreadsheets/d/your_sheet_id" 并设置最大行数为 500
url
(必需):Google表格URL
max_rows
(可选):每个工作表的最大行数(默认:1000)
sheets
(可选):要同步的特定工作表名称数组
query_sheets
对同步的数据运行SQL查询,包括跨标签的JOIN操作。
使用 query_sheets 执行查询 "SELECT * FROM sheet1 JOIN sheet2 ON sheet1.id = sheet2.id LIMIT 10"
list_synced_sheets
查看所有已同步的工作表及其表名。
使用 list_synced_sheets
analyze_sheets
获取跨多个工作表的查询建议。
使用 analyze_sheets 并提出问题 "如何将销售数据与客户数据结合起来?"
get_sheet_preview
无需同步即可快速预览。
使用 get_sheet_preview,指定URL "https://docs.google.com/spreadsheets/d/your_sheet_id" 并设置预览行数为 20
url
(必需):Google表格URL
sheet_name
(可选):要预览的特定工作表
rows
(可选):要预览的行数(默认:10)
📚 详细文档
📊 工作原理
- 身份验证:使用OAuth2安全访问Google表格API。
- 同步:将表格数据下载到本地SQLite数据库,并可配置限制。
- 查询:支持对所有已同步的工作表进行SQL查询。
- 多标签:每个工作表成为一个单独的表,可通过SQL进行连接。
🏗️ 项目结构
google-sheet-analytics-mcp/
├── src/
│ ├── mcp_server.py # 主MCP服务器实现
│ └── auth/
│ └── oauth_setup.py # 统一的OAuth身份验证模块
├── setup.py # 统一的设置脚本(处理所有事情)
├── requirements.txt # Python依赖项
├── credentials.json.example # 示例OAuth凭据格式
├── README.md # 本文件
├── LICENSE # MIT许可证
├── CLAUDE.md # Claude特定说明
├── data/ # 运行时数据(自动创建)
│ ├── token.json # OAuth令牌(设置期间创建)
│ └── sheets_data.sqlite # 本地数据库(首次同步时创建)
└── venv/ # 虚拟环境(设置期间创建)
⚡ 性能
- 行限制:每个工作表默认1000行(可配置)。
- 结果限制:查询结果限制为100行。
- 本地存储:使用SQLite数据库进行快速重复查询。
- 元数据跟踪:高效重新同步更改的数据。
- 内存高效:采用流式数据处理。
🔍 示例用例
上述使用示例部分已提供了多标签分析和跨工作表聚合的示例。
🔧 技术细节
身份验证
使用OAuth2协议确保安全访问Google表格API。通过 src/auth/oauth_setup.py
模块进行统一的OAuth身份验证设置。
数据同步
将Google表格数据下载到本地SQLite数据库,可通过配置行限制来控制同步的数据量。在首次同步时会创建 data/sheets_data.sqlite
数据库文件。
SQL查询
支持对同步到本地数据库的所有工作表进行SQL查询,包括跨标签的JOIN操作。每个工作表在数据库中作为一个单独的表存在。
性能优化
通过设置行限制、结果限制、本地存储、元数据跟踪和流式数据处理等方式,确保服务器在处理大型数据集时具有良好的性能。
📄 许可证
本项目采用MIT许可证,详情请参阅 LICENSE 文件。
🙏 致谢
需要帮助? 在GitHub上创建一个问题或查看上述故障排除部分。
🐛 故障排除
常见问题
问题 |
解决方案 |
"未找到凭据" |
确保 credentials.json 存在于项目根目录或 config/ 目录中 |
"身份验证失败" |
使用 venv/bin/python src/auth/oauth_setup.py --status 检查令牌状态 |
"令牌过期" |
运行 venv/bin/python src/auth/oauth_setup.py --test (自动刷新) |
"同步超时" |
减少 smart_sync 中的 max_rows 参数 |
"工具未显示" |
配置后重启Claude Desktop |
"速率限制错误" |
等待几分钟后,以较小的批次重试 |
OAuth故障排除
- 检查状态:
venv/bin/python src/auth/oauth_setup.py --status
- 测试身份验证:
venv/bin/python src/auth/oauth_setup.py --test
- 重置OAuth:
venv/bin/python src/auth/oauth_setup.py --reset
- 手动设置:
venv/bin/python src/auth/oauth_setup.py --manual
MCP服务器未显示
- 确保Claude Desktop已完全关闭。
- 验证配置:
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
- 检查配置中是否包含google-sheets-analytics服务器。
- 重启Claude Desktop。
- 检查开发者控制台是否有错误信息。
数据库问题
- 数据库位置:
data/sheets_data.sqlite
- 重置数据库:删除该文件并重新同步。
- 检查已同步的工作表:使用
list_synced_sheets
工具。
🤝 贡献
- 分叉仓库。
- 创建一个功能分支 (
git checkout -b feature/amazing-feature
)。
- 提交更改 (
git commit -m '添加惊人的功能'
)。
- 推送到该分支 (
git push origin feature/amazing-feature
)。
- 打开一个拉取请求。