[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-xing5--mcp-google-sheets":3,"tool-xing5--mcp-google-sheets":64},[4,17,27,35,48,56],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":16},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,3,"2026-04-05T11:01:52",[13,14,15],"开发框架","图像","Agent","ready",{"id":18,"name":19,"github_repo":20,"description_zh":21,"stars":22,"difficulty_score":23,"last_commit_at":24,"category_tags":25,"status":16},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",138956,2,"2026-04-05T11:33:21",[13,15,26],"语言模型",{"id":28,"name":29,"github_repo":30,"description_zh":31,"stars":32,"difficulty_score":23,"last_commit_at":33,"category_tags":34,"status":16},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107662,"2026-04-03T11:11:01",[13,14,15],{"id":36,"name":37,"github_repo":38,"description_zh":39,"stars":40,"difficulty_score":23,"last_commit_at":41,"category_tags":42,"status":16},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",84991,"2026-04-05T10:45:23",[14,43,44,45,15,46,26,13,47],"数据工具","视频","插件","其他","音频",{"id":49,"name":50,"github_repo":51,"description_zh":52,"stars":53,"difficulty_score":10,"last_commit_at":54,"category_tags":55,"status":16},3128,"ragflow","infiniflow\u002Fragflow","RAGFlow 是一款领先的开源检索增强生成（RAG）引擎，旨在为大语言模型构建更精准、可靠的上下文层。它巧妙地将前沿的 RAG 技术与智能体（Agent）能力相结合，不仅支持从各类文档中高效提取知识，还能让模型基于这些知识进行逻辑推理和任务执行。\n\n在大模型应用中，幻觉问题和知识滞后是常见痛点。RAGFlow 通过深度解析复杂文档结构（如表格、图表及混合排版），显著提升了信息检索的准确度，从而有效减少模型“胡编乱造”的现象，确保回答既有据可依又具备时效性。其内置的智能体机制更进一步，使系统不仅能回答问题，还能自主规划步骤解决复杂问题。\n\n这款工具特别适合开发者、企业技术团队以及 AI 研究人员使用。无论是希望快速搭建私有知识库问答系统，还是致力于探索大模型在垂直领域落地的创新者，都能从中受益。RAGFlow 提供了可视化的工作流编排界面和灵活的 API 接口，既降低了非算法背景用户的上手门槛，也满足了专业开发者对系统深度定制的需求。作为基于 Apache 2.0 协议开源的项目，它正成为连接通用大模型与行业专有知识之间的重要桥梁。",77062,"2026-04-04T04:44:48",[15,14,13,26,46],{"id":57,"name":58,"github_repo":59,"description_zh":60,"stars":61,"difficulty_score":10,"last_commit_at":62,"category_tags":63,"status":16},2181,"OpenHands","OpenHands\u002FOpenHands","OpenHands 是一个专注于 AI 驱动开发的开源平台，旨在让智能体（Agent）像人类开发者一样理解、编写和调试代码。它解决了传统编程中重复性劳动多、环境配置复杂以及人机协作效率低等痛点，通过自动化流程显著提升开发速度。\n\n无论是希望提升编码效率的软件工程师、探索智能体技术的研究人员，还是需要快速原型验证的技术团队，都能从中受益。OpenHands 提供了灵活多样的使用方式：既可以通过命令行（CLI）或本地图形界面在个人电脑上轻松上手，体验类似 Devin 的流畅交互；也能利用其强大的 Python SDK 自定义智能体逻辑，甚至在云端大规模部署上千个智能体并行工作。\n\n其核心技术亮点在于模块化的软件智能体 SDK，这不仅构成了平台的引擎，还支持高度可组合的开发模式。此外，OpenHands 在 SWE-bench 基准测试中取得了 77.6% 的优异成绩，证明了其解决真实世界软件工程问题的能力。平台还具备完善的企业级功能，支持与 Slack、Jira 等工具集成，并提供细粒度的权限管理，适合从个人开发者到大型企业的各类用户场景。",70612,"2026-04-05T11:12:22",[26,15,13,45],{"id":65,"github_repo":66,"name":67,"description_en":68,"description_zh":69,"ai_summary_zh":70,"readme_en":71,"readme_zh":72,"quickstart_zh":73,"use_case_zh":74,"hero_image_url":75,"owner_login":76,"owner_name":77,"owner_avatar_url":78,"owner_bio":79,"owner_company":79,"owner_location":80,"owner_email":81,"owner_twitter":79,"owner_website":82,"owner_url":83,"languages":84,"stars":93,"forks":94,"last_commit_at":95,"license":96,"difficulty_score":23,"env_os":97,"env_gpu":98,"env_ram":98,"env_deps":99,"category_tags":104,"github_topics":105,"view_count":23,"oss_zip_url":79,"oss_zip_packed_at":79,"status":16,"created_at":110,"updated_at":111,"faqs":112,"releases":142},3136,"xing5\u002Fmcp-google-sheets","mcp-google-sheets","This MCP server integrates with your Google Drive and Google Sheets, to enable creating and modifying spreadsheets.","mcp-google-sheets 是一款基于 Python 开发的开源工具，旨在充当 AI 助手与谷歌表格（Google Sheets）之间的智能桥梁。它通过模型上下文协议（MCP），让兼容的 AI 客户端（如 Claude Desktop）能够直接读取、创建和修改你的电子表格数据，将自然语言指令转化为具体的表格操作。\n\n这一工具主要解决了 AI 无法直接访问或操作用户云端数据的痛点。以往用户需要手动在 AI 对话和表格软件间复制粘贴数据，流程繁琐且易错；而 mcp-google-sheets 实现了自动化闭环，让用户能通过简单的对话完成复杂的数据整理、报表生成及工作流自动化任务。\n\n它特别适合希望提升办公效率的普通用户、需要处理大量数据的分析师，以及想要为 AI 应用集成表格功能的开发者。对于熟悉命令行操作的技术人员，它能快速嵌入现有工作流；对于非技术用户，配合支持 MCP 的 AI 桌面端，也能轻松享受“动口不动手”的数据管理体验。\n\n其技术亮点在于轻量化的部署方式，仅需一行命令即可通过 `uvx` 启动最新服务，无需复杂的环境配置。同时，它支持多种认证模式，推荐使用谷歌云服务账","mcp-google-sheets 是一款基于 Python 开发的开源工具，旨在充当 AI 助手与谷歌表格（Google Sheets）之间的智能桥梁。它通过模型上下文协议（MCP），让兼容的 AI 客户端（如 Claude Desktop）能够直接读取、创建和修改你的电子表格数据，将自然语言指令转化为具体的表格操作。\n\n这一工具主要解决了 AI 无法直接访问或操作用户云端数据的痛点。以往用户需要手动在 AI 对话和表格软件间复制粘贴数据，流程繁琐且易错；而 mcp-google-sheets 实现了自动化闭环，让用户能通过简单的对话完成复杂的数据整理、报表生成及工作流自动化任务。\n\n它特别适合希望提升办公效率的普通用户、需要处理大量数据的分析师，以及想要为 AI 应用集成表格功能的开发者。对于熟悉命令行操作的技术人员，它能快速嵌入现有工作流；对于非技术用户，配合支持 MCP 的 AI 桌面端，也能轻松享受“动口不动手”的数据管理体验。\n\n其技术亮点在于轻量化的部署方式，仅需一行命令即可通过 `uvx` 启动最新服务，无需复杂的环境配置。同时，它支持多种认证模式，推荐使用谷歌云服务账号以确保企业级的数据安全与稳定连接，是构建本地化 AI 数据助手的理想选择。","\u003Cdiv align=\"center\">\n \u003C!-- Main Title Link -->\n \u003Cb>mcp-google-sheets\u003C\u002Fb>\n\n \u003C!-- Description Paragraph -->\n \u003Cp align=\"center\">\n \u003Ci>Your AI Assistant's Gateway to Google Sheets! \u003C\u002Fi>📊\n \u003C\u002Fp>\n\n[![PyPI - Version](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fmcp-google-sheets)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fmcp-google-sheets\u002F)\n[![PyPI Downloads](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fxing5_mcp-google-sheets_readme_a397c9b5ce36.png)](https:\u002F\u002Fpepy.tech\u002Fprojects\u002Fmcp-google-sheets)\n![GitHub License](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fxing5\u002Fmcp-google-sheets)\n![GitHub Actions Workflow Status](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Factions\u002Fworkflow\u002Fstatus\u002Fxing5\u002Fmcp-google-sheets\u002Frelease.yml)\n\u003C\u002Fdiv>\n\n---\n\n## 🤔 What is this?\n\n`mcp-google-sheets` is a Python-based MCP server that acts as a bridge between any MCP-compatible client (like Claude Desktop) and the Google Sheets API. It allows you to interact with your Google Spreadsheets using a defined set of tools, enabling powerful automation and data manipulation workflows driven by AI.\n\n---\n\n## 🚀 Quick Start (Using `uvx`)\n\nEssentially the server runs in one line: `uvx mcp-google-sheets@latest`. \n\nThis command will automatically download the latest code and run it. **We recommend always using `@latest`** to ensure you have the newest version with the latest features and bug fixes.\n\n_Refer to the [ID Reference Guide](#-id-reference-guide) for more information about the IDs used below._\n\n1. **☁️ Prerequisite: Google Cloud Setup**\n * You **must** configure Google Cloud Platform credentials and enable the necessary APIs first. We strongly recommend using a **Service Account**.\n * ➡️ Jump to the [**Detailed Google Cloud Platform Setup**](#-google-cloud-platform-setup-detailed) guide below.\n\n2. **🐍 Install `uv`**\n * `uvx` is part of `uv`, a fast Python package installer and resolver. Install it if you haven't already:\n ```bash\n # macOS \u002F Linux\n curl -LsSf https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.sh | sh\n # Windows\n powershell -c \"irm https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.ps1 | iex\"\n # Or using pip:\n # pip install uv\n ```\n *Follow instructions in the installer output to add `uv` to your PATH if needed.*\n\n3. **🔑 Set Essential Environment Variables (Service Account Recommended)**\n * You need to tell the server how to authenticate. Set these variables in your terminal:\n * **(Linux\u002FmacOS)**\n ```bash\n # Replace with YOUR actual path and folder ID from the Google Setup step\n export SERVICE_ACCOUNT_PATH=\"\u002Fpath\u002Fto\u002Fyour\u002Fservice-account-key.json\"\n export DRIVE_FOLDER_ID=\"YOUR_DRIVE_FOLDER_ID\"\n ```\n * **(Windows CMD)**\n ```cmd\n set SERVICE_ACCOUNT_PATH=\"C:\\path\\to\\your\\service-account-key.json\"\n set DRIVE_FOLDER_ID=\"YOUR_DRIVE_FOLDER_ID\"\n ```\n * **(Windows PowerShell)**\n ```powershell\n $env:SERVICE_ACCOUNT_PATH = \"C:\\path\\to\\your\\service-account-key.json\"\n $env:DRIVE_FOLDER_ID = \"YOUR_DRIVE_FOLDER_ID\"\n ```\n * ➡️ See [**Detailed Authentication & Environment Variables**](#-authentication--environment-variables-detailed) for other options (OAuth, `CREDENTIALS_CONFIG`).\n\n4. **🏃 Run the Server!**\n * `uvx` will automatically download and run the latest version of `mcp-google-sheets`:\n ```bash\n uvx mcp-google-sheets@latest\n ```\n * The server will start and print logs indicating it's ready.\n * \n * > **💡 Pro Tip:** Always use `@latest` to ensure you get the newest version with bug fixes and features. Without `@latest`, `uvx` may use a cached older version.\n\n5. **🔌 Connect your MCP Client**\n * Configure your client (e.g., Claude Desktop) to connect to the running server.\n * Depending on the client you use, you might not need step 4 because the client can launch the server for you. But it's a good practice to test run step 4 anyway to make sure things are set up properly.\n * ➡️ See [**Usage with Claude Desktop**](#-usage-with-claude-desktop) for examples.\n\n6. **⚡ Optional: Enable Tool Filtering (Reduce Context Usage)**\n * By default, all 19 tools are enabled (~13K tokens). To reduce context usage, enable only the tools you need.\n * ➡️ See [**Tool Filtering**](#-tool-filtering-reduce-context-usage) for details.\n\nYou're ready! Start issuing commands via your MCP client.\n\n---\n\n## ✨ Key Features\n\n* **Seamless Integration:** Connects directly to Google Drive & Google Sheets APIs.\n* **Comprehensive Tools:** Offers a wide range of operations (CRUD, listing, batching, sharing, formatting, etc.).\n* **Flexible Authentication:** Supports **Service Accounts (recommended)**, OAuth 2.0, and direct credential injection via environment variables.\n* **Easy Deployment:** Run instantly with `uvx` (zero-install feel) or clone for development using `uv`.\n* **AI-Ready:** Designed for use with MCP-compatible clients, enabling natural language spreadsheet interaction.\n* **Tool Filtering:** Reduce context window usage by enabling only the tools you need with `--include-tools` or `ENABLED_TOOLS` environment variable.\n\n---\n\n## 🎯 Tool Filtering (Reduce Context Usage)\n\n**Problem:** By default, this MCP server exposes all 19 tools, consuming ~13,000 tokens before any conversation begins. If you only need a few tools, this wastes valuable context window space.\n\n**Solution:** Use tool filtering to enable only the tools you actually use.\n\n### How to Enable Tool Filtering\n\nYou can filter tools using either:\n\n1. **Command-line argument** `--include-tools`:\n ```json\n {\n \"mcpServers\": {\n \"google-sheets\": {\n \"command\": \"uvx\",\n \"args\": [\n \"mcp-google-sheets@latest\",\n \"--include-tools\",\n \"get_sheet_data,update_cells,list_spreadsheets,list_sheets\"\n ],\n \"env\": {\n \"SERVICE_ACCOUNT_PATH\": \"\u002Fpath\u002Fto\u002Fcredentials.json\"\n }\n }\n }\n }\n ```\n\n2. **Environment variable** `ENABLED_TOOLS`:\n ```json\n {\n \"mcpServers\": {\n \"google-sheets\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-google-sheets@latest\"],\n \"env\": {\n \"SERVICE_ACCOUNT_PATH\": \"\u002Fpath\u002Fto\u002Fcredentials.json\",\n \"ENABLED_TOOLS\": \"get_sheet_data,update_cells,list_spreadsheets,list_sheets\"\n }\n }\n }\n }\n ```\n\n### Available Tool Names\n\nWhen filtering, use these exact tool names (comma-separated, no spaces):\n\n**Most Common Tools (recommended subset):**\n- `get_sheet_data` - Read from spreadsheets\n- `update_cells` - Write to spreadsheets\n- `list_spreadsheets` - Find spreadsheets\n- `list_sheets` - Navigate tabs\n\n**All Available Tools:**\n- `add_columns`\n- `add_rows`\n- `batch_update`\n- `batch_update_cells`\n- `copy_sheet`\n- `create_sheet`\n- `create_spreadsheet`\n- `find_in_spreadsheet`\n- `get_multiple_sheet_data`\n- `get_multiple_spreadsheet_summary`\n- `get_sheet_data`\n- `get_sheet_formulas`\n- `list_folders`\n- `list_sheets`\n- `list_spreadsheets`\n- `rename_sheet`\n- `search_spreadsheets`\n- `share_spreadsheet`\n- `update_cells`\n\n**Note:** If neither `--include-tools` nor `ENABLED_TOOLS` is specified, all tools are enabled (default behavior).\n\n---\n\n## 🛠️ Available Tools & Resources\n\nThis server exposes the following tools for interacting with Google Sheets:\n\n_Refer to the [ID Reference Guide](#-id-reference-guide) for more information about the IDs used below._\n\n*(Input parameters are typically strings unless otherwise specified)*\n\n* **`list_spreadsheets`**: Lists spreadsheets in the configured Drive folder (Service Account) or accessible by the user (OAuth).\n * `folder_id` (optional string): Google Drive folder ID to search in. Get from its URL. If omitted, uses the configured default folder or searches 'My Drive'.\n * _Returns:_ List of objects `[{id: string, title: string}]`\n* **`create_spreadsheet`**: Creates a new spreadsheet.\n * `title` (string): The desired title for the spreadsheet. Example: \"Quarterly Report Q4\".\n * `folder_id` (optional string): Google Drive folder ID where the spreadsheet should be created. Get from its URL. If omitted, uses configured default or root.\n * _Returns:_ Object with spreadsheet info, including `spreadsheetId`, `title`, and `folder`.\n* **`get_sheet_data`**: Reads data from a range in a sheet\u002Ftab.\n * `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n * `sheet` (string): Name of the sheet\u002Ftab (e.g., \"Sheet1\").\n * `range` (optional string): A1 notation (e.g., `'A1:C10'`, `'Sheet1!B2:D'`). If omitted, reads the whole sheet\u002Ftab specified by `sheet`.\n * `include_grid_data` (optional boolean, default `False`): If `True`, returns full grid data including formatting and metadata (much larger). If `False`, returns values only (more efficient).\n * _Returns:_ If `include_grid_data=True`, full grid data with metadata ([`get` response](https:\u002F\u002Fdevelopers.google.com\u002Fworkspace\u002Fsheets\u002Fapi\u002Freference\u002Frest\u002Fv4\u002Fspreadsheets\u002Fget#response-body)). If `False`, a values result object from the Values API ([`values.get` response](https:\u002F\u002Fdevelopers.google.com\u002Fworkspace\u002Fsheets\u002Fapi\u002Freference\u002Frest\u002Fv4\u002Fspreadsheets.values\u002Fget#response-body)).\n* **`get_sheet_formulas`**: Reads formulas from a range in a sheet\u002Ftab.\n * `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n * `sheet` (string): Name of the sheet\u002Ftab (e.g., \"Sheet1\").\n * `range` (optional string): A1 notation (e.g., `'A1:C10'`, `'Sheet1!B2:D'`). If omitted, reads all formulas in the sheet\u002Ftab specified by `sheet`.\n * _Returns:_ 2D array of cell formulas (array of arrays) ([`values.get` response](https:\u002F\u002Fdevelopers.google.com\u002Fworkspace\u002Fsheets\u002Fapi\u002Freference\u002Frest\u002Fv4\u002Fspreadsheets.values\u002Fget#response-body)).\n* **`update_cells`**: Writes data to a specific range. Overwrites existing data.\n * `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n * `sheet` (string): Name of the sheet\u002Ftab (e.g., \"Sheet1\").\n * `range` (string): A1 notation range to write to (e.g., 'A1:C3').\n * `data` (array of arrays): 2D array of values to write. Example: `[[1, 2, 3], [\"a\", \"b\", \"c\"]]`.\n * _Returns:_ Update result object ([`values.update` response](https:\u002F\u002Fdevelopers.google.com\u002Fworkspace\u002Fsheets\u002Fapi\u002Freference\u002Frest\u002Fv4\u002Fspreadsheets.values\u002Fupdate#response-body)).\n* **`batch_update_cells`**: Updates multiple ranges in one API call.\n * `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n * `sheet` (string): Name of the sheet\u002Ftab (e.g., \"Sheet1\").\n * `ranges` (object): Dictionary mapping range strings (A1 notation) to 2D arrays of values. Example: `{ \"A1:B2\": [[1, 2], [3, 4]], \"D5\": [[\"Hello\"]] }`.\n * _Returns:_ Result of the operation ([`values.batchUpdate` response](https:\u002F\u002Fdevelopers.google.com\u002Fworkspace\u002Fsheets\u002Fapi\u002Freference\u002Frest\u002Fv4\u002Fspreadsheets.values\u002FbatchUpdate#response-body)).\n* **`add_rows`**: Adds (inserts) empty rows to a sheet\u002Ftab at a specified index.\n * `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n * `sheet` (string): Name of the sheet\u002Ftab (e.g., \"Sheet1\").\n * `count` (integer): Number of empty rows to insert.\n * `start_row` (optional integer, default `0`): 0-based row index to start inserting rows. If omitted, defaults to `0` (inserts at the beginning).\n * _Returns:_ Result of the operation ([`batchUpdate` response](https:\u002F\u002Fdevelopers.google.com\u002Fworkspace\u002Fsheets\u002Fapi\u002Freference\u002Frest\u002Fv4\u002Fspreadsheets\u002FbatchUpdate#response-body)).\n* **`list_sheets`**: Lists all sheet\u002Ftab names within a spreadsheet.\n * `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n * _Returns:_ List of sheet\u002Ftab name strings. Example: `[\"Sheet1\", \"Sheet2\"]`.\n* **`create_sheet`**: Adds a new sheet\u002Ftab to a spreadsheet.\n * `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n * `title` (string): Name for the new sheet\u002Ftab.\n * _Returns:_ New sheet properties object.\n* **`get_multiple_sheet_data`**: Fetches data from multiple ranges across potentially different spreadsheets in one call.\n * `queries` (array of objects): Each object needs `spreadsheet_id`, `sheet`, and `range`. Example: `[{\"spreadsheet_id\": \"abc\", \"sheet\": \"Sheet1\", \"range\": \"A1:B2\"}, ...]`.\n * _Returns:_ List of objects, each containing the query params and fetched `data` or an `error`. Each `data` is a [`values.get` response](https:\u002F\u002Fdevelopers.google.com\u002Fworkspace\u002Fsheets\u002Fapi\u002Freference\u002Frest\u002Fv4\u002Fspreadsheets.values\u002Fget#response-body).\n* **`get_multiple_spreadsheet_summary`**: Gets titles, sheet\u002Ftab names, headers, and first few rows for multiple spreadsheets.\n * `spreadsheet_ids` (array of strings): IDs of the spreadsheets (from their URLs).\n * `rows_to_fetch` (optional integer, default `5`): How many rows (including header) to preview. Example: `5`.\n * _Returns:_ List of summary objects for each spreadsheet.\n* **`share_spreadsheet`**: Shares a spreadsheet with specified users\u002Femails and roles.\n * `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n * `recipients` (array of objects): `[{\"email_address\": \"user@example.com\", \"role\": \"writer\"}, ...]`. Roles: `reader`, `commenter`, `writer`.\n * `send_notification` (optional boolean, default `True`): Send email notifications to recipients.\n * _Returns:_ Dictionary with `successes` and `failures` lists.\n* **`add_columns`**: Adds (inserts) empty columns to a sheet\u002Ftab at a specified index.\n * `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n * `sheet` (string): Name of the sheet\u002Ftab (e.g., \"Sheet1\").\n * `count` (integer): Number of empty columns to insert.\n * `start_column` (optional integer, default `0`): 0-based column index to start inserting. If omitted, defaults to `0` (inserts at the beginning).\n * _Returns:_ Result of the operation ([`batchUpdate` response](https:\u002F\u002Fdevelopers.google.com\u002Fworkspace\u002Fsheets\u002Fapi\u002Freference\u002Frest\u002Fv4\u002Fspreadsheets\u002FbatchUpdate#response-body)).\n* **`copy_sheet`**: Duplicates a sheet\u002Ftab from one spreadsheet to another and optionally renames it.\n * `src_spreadsheet` (string): Source spreadsheet ID (from its URL).\n * `src_sheet` (string): Source sheet\u002Ftab name (e.g., \"Sheet1\").\n * `dst_spreadsheet` (string): Destination spreadsheet ID (from its URL).\n * `dst_sheet` (string): Desired sheet\u002Ftab name in the destination spreadsheet.\n * _Returns:_ Result of the copy and optional rename operations.\n* **`rename_sheet`**: Renames an existing sheet\u002Ftab.\n * `spreadsheet` (string): The spreadsheet ID (from its URL).\n * `sheet` (string): Current sheet\u002Ftab name (e.g., \"Sheet1\").\n * `new_name` (string): New sheet\u002Ftab name (e.g., \"Transactions\").\n * _Returns:_ Result of the operation ([`batchUpdate` response](https:\u002F\u002Fdevelopers.google.com\u002Fworkspace\u002Fsheets\u002Fapi\u002Freference\u002Frest\u002Fv4\u002Fspreadsheets\u002FbatchUpdate#response-body)).\n* **`add_chart`**: Creates a chart in a Google Spreadsheet from specified data.\n * `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n * `sheet` (string): Name of the sheet\u002Ftab containing the data (e.g., \"Sheet1\").\n * `chart_type` (string): Type of chart to create. Options: `COLUMN` (vertical bars), `BAR` (horizontal bars), `LINE`, `AREA`, `PIE`, `SCATTER`, `COMBO`, `HISTOGRAM`.\n * `data_range` (string): A1 notation range for the chart data (e.g., \"A1:C10\"). First row is treated as headers.\n * `title` (optional string): Chart title.\n * `x_axis_label` (optional string): Label for the X axis (bottom axis). Not applicable for pie charts.\n * `y_axis_label` (optional string): Label for the Y axis (left axis). Not applicable for pie charts.\n * `position_x` (optional integer, default `0`): Horizontal position offset in pixels from the top-left corner.\n * `position_y` (optional integer, default `0`): Vertical position offset in pixels from the top-left corner.\n * `width` (optional integer, default `600`): Width of the chart in pixels.\n * `height` (optional integer, default `400`): Height of the chart in pixels.\n * _Returns:_ Result object with success status, chart ID, and operation details.\n\n**MCP Resources:**\n\n* **`spreadsheet:\u002F\u002F{spreadsheet_id}\u002Finfo`**: Get basic metadata about a Google Spreadsheet.\n * _Returns:_ JSON string with spreadsheet information.\n\n---\n\n## ☁️ Google Cloud Platform Setup (Detailed)\n\nThis setup is **required** before running the server.\n\n1. **Create\u002FSelect a GCP Project:** Go to the [Google Cloud Console](https:\u002F\u002Fconsole.cloud.google.com\u002F).\n2. **Enable APIs:** Navigate to \"APIs & Services\" -> \"Library\". Search for and enable:\n * `Google Sheets API`\n * `Google Drive API`\n3. **Configure Credentials:** You need to choose *one* authentication method below (Service Account is recommended).\n\n---\n\n## 🔑 Authentication & Environment Variables (Detailed)\n\nThe server needs credentials to access Google APIs. Choose one method:\n\n_Refer to the [ID Reference Guide](#-id-reference-guide) for more information about the IDs used below._\n\n### Method A: Service Account (Recommended for Servers\u002FAutomation) ✅\n\n* **Why?** Headless (no browser needed), secure, ideal for server environments. Doesn't expire easily.\n* **Steps:**\n 1. **Create Service Account:** In GCP Console -> \"IAM & Admin\" -> \"Service Accounts\".\n * Click \"+ CREATE SERVICE ACCOUNT\". Name it (e.g., `mcp-sheets-service`).\n * Grant Roles: Add `Editor` role for broad access, or more granular roles (like `roles\u002Fdrive.file` and specific Sheets roles) for stricter permissions.\n * Click \"Done\". Find the account, click Actions (⋮) -> \"Manage keys\".\n * Click \"ADD KEY\" -> \"Create new key\" -> **JSON** -> \"CREATE\".\n * **Download and securely store** the JSON key file.\n 2. **Create & Share Google Drive Folder:**\n * In [Google Drive](https:\u002F\u002Fdrive.google.com\u002F), create a folder (e.g., \"AI Managed Sheets\").\n * Note the **Folder ID** from the URL: `https:\u002F\u002Fdrive.google.com\u002Fdrive\u002Ffolders\u002FTHIS_IS_THE_FOLDER_ID`.\n * Right-click the folder -> \"Share\" -> \"Share\".\n * Enter the Service Account's email (from the JSON file `client_email`).\n * Grant **Editor** access. Uncheck \"Notify people\". Click \"Share\".\n 3. **Set Environment Variables:**\n * `SERVICE_ACCOUNT_PATH`: Full path to the downloaded JSON key file.\n * `DRIVE_FOLDER_ID`: The ID of the shared Google Drive folder.\n *(See [Ultra Quick Start](#-ultra-quick-start-using-uvx) for OS-specific examples)*\n\n### Method B: OAuth 2.0 (Interactive \u002F Personal Use) 🧑‍💻\n\n* **Why?** For personal use or local development where interactive browser login is okay.\n* **Steps:**\n 1. **Configure OAuth Consent Screen:** In GCP Console -> \"APIs & Services\" -> \"OAuth consent screen\". Select \"External\", fill required info, add scopes (`...\u002Fauth\u002Fspreadsheets`, `...\u002Fauth\u002Fdrive`), add test users if needed.\n 2. **Create OAuth Client ID:** In GCP Console -> \"APIs & Services\" -> \"Credentials\". \"+ CREATE CREDENTIALS\" -> \"OAuth client ID\" -> Type: **Desktop app**. Name it. \"CREATE\". **Download JSON**.\n 3. **Set Environment Variables:**\n * `CREDENTIALS_PATH`: Path to the downloaded OAuth credentials JSON file (default: `credentials.json`).\n * `TOKEN_PATH`: Path to store the user's refresh token after first login (default: `token.json`). Must be writable.\n\n### Method C: Direct Credential Injection (Advanced) 🔒\n\n* **Why?** Useful in environments like Docker, Kubernetes, or CI\u002FCD where managing files is hard, but environment variables are easy\u002Fsecure. Avoids file system access.\n* **How?** Instead of providing a *path* to the credentials file, you provide the *content* of the file, encoded in Base64, directly in an environment variable.\n* **Steps:**\n 1. **Get your credentials JSON file** (either Service Account key or OAuth Client ID file). Let's call it `your_credentials.json`.\n 2. **Generate the Base64 string:**\n * **(Linux\u002FmacOS):** `base64 -w 0 your_credentials.json`\n * **(Windows PowerShell):**\n ```powershell\n $filePath = \"C:\\path\\to\\your_credentials.json\"; # Use actual path\n $bytes = [System.IO.File]::ReadAllBytes($filePath);\n $base64 = [System.Convert]::ToBase64String($bytes);\n $base64 # Copy this output\n ```\n * **(Caution):** Avoid pasting sensitive credentials into untrusted online encoders.\n 3. **Set the Environment Variable:**\n * `CREDENTIALS_CONFIG`: Set this variable to the **full Base64 string** you just generated.\n ```bash\n # Example (Linux\u002FmacOS) - Use the actual string generated\n export CREDENTIALS_CONFIG=\"ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb...\"\n ```\n\n### Method D: Application Default Credentials (ADC) 🌐\n\n* **Why?** Ideal for Google Cloud environments (GKE, Compute Engine, Cloud Run) and local development with `gcloud auth application-default login`. No explicit credential files needed.\n* **How?** Uses Google's Application Default Credentials chain to automatically discover credentials from multiple sources.\n* **ADC Search Order:**\n 1. `GOOGLE_APPLICATION_CREDENTIALS` environment variable (path to service account key) - **Google's standard variable**\n 2. `gcloud auth application-default login` credentials (local development)\n 3. Attached service account from metadata server (GKE, Compute Engine, etc.)\n* **Setup:**\n * **Local Development:** \n 1. Run `gcloud auth application-default login --scopes=https:\u002F\u002Fwww.googleapis.com\u002Fauth\u002Fcloud-platform,https:\u002F\u002Fwww.googleapis.com\u002Fauth\u002Fspreadsheets,https:\u002F\u002Fwww.googleapis.com\u002Fauth\u002Fdrive` once\n 2. Set a quota project: `gcloud auth application-default set-quota-project \u003Cproject_id>` (replace `\u003Cproject_id>` with your Google Cloud project ID)\n * **Google Cloud:** Attach a service account to your compute resource\n * **Environment Variable:** Set `GOOGLE_APPLICATION_CREDENTIALS=\u002Fpath\u002Fto\u002Fservice-account.json` (Google's standard)\n* **No additional environment variables needed** - ADC is used automatically as a fallback when other methods fail.\n\n**Note:** `GOOGLE_APPLICATION_CREDENTIALS` is Google's official standard environment variable, while `SERVICE_ACCOUNT_PATH` is specific to this MCP server. If you set `GOOGLE_APPLICATION_CREDENTIALS`, ADC will find it automatically.\n\n### Authentication Priority & Summary\n\nThe server checks for credentials in this order:\n\n1. `CREDENTIALS_CONFIG` (Base64 content)\n2. `SERVICE_ACCOUNT_PATH` (Path to Service Account JSON)\n3. `CREDENTIALS_PATH` (Path to OAuth JSON) - triggers interactive flow if token is missing\u002Fexpired\n4. **Application Default Credentials (ADC)** - automatic fallback\n\n**Environment Variable Summary:**\n\n| Variable | Method(s) | Description | Default |\n|:---------------------------------|:----------------------------|:-----------------------------------------------------------------|:-------------------|\n| `SERVICE_ACCOUNT_PATH` | Service Account | Path to the Service Account JSON key file (MCP server specific). | - |\n| `GOOGLE_APPLICATION_CREDENTIALS` | ADC | Path to service account key (Google's standard variable). | - |\n| `DRIVE_FOLDER_ID` | Service Account | ID of the Google Drive folder shared with the Service Account. | - |\n| `CREDENTIALS_PATH` | OAuth 2.0 | Path to the OAuth 2.0 Client ID JSON file. | `credentials.json` |\n| `TOKEN_PATH` | OAuth 2.0 | Path to store the generated OAuth token. | `token.json` |\n| `CREDENTIALS_CONFIG` | Service Account \u002F OAuth 2.0 | Base64 encoded JSON string of credentials content. | - |\n\n---\n\n## ⚙️ Running the Server (Detailed)\n\n_Refer to the [ID Reference Guide](#-id-reference-guide) for more information about the IDs used below._\n\n### Method 1: Using `uvx` (Recommended for Users)\n\nAs shown in the [Ultra Quick Start](#-ultra-quick-start-using-uvx), this is the easiest way. Set environment variables, then run:\n\n```bash\nuvx mcp-google-sheets@latest\n```\n`uvx` handles fetching and running the package temporarily.\n\n### Method 2: For Development (Cloning the Repo)\n\nIf you want to modify the code:\n\n1. **Clone:** `git clone https:\u002F\u002Fgithub.com\u002Fyourusername\u002Fmcp-google-sheets.git && cd mcp-google-sheets` (Use actual URL)\n2. **Set Environment Variables:** As described above.\n3. **Run using `uv`:** (Uses the local code)\n ```bash\n uv run mcp-google-sheets\n # Or via the script name if defined in pyproject.toml, e.g.:\n # uv run start\n ```\n\n### Method 3: Docker (SSE transport)\n\nRun the server in a container using the included `Dockerfile`:\n\n```bash\n# Build the image\ndocker build -t mcp-google-sheets .\n\n# Run (SSE on port 8000)\n# NOTE: Prefer CREDENTIALS_CONFIG (Base64 credentials content) in containers.\ndocker run --rm -p 8000:8000 ^\n -e HOST=0.0.0.0 ^\n -e PORT=8000 ^\n -e CREDENTIALS_CONFIG=YOUR_BASE64_CREDENTIALS ^\n -e DRIVE_FOLDER_ID=YOUR_DRIVE_FOLDER_ID ^\n mcp-google-sheets\n```\n\n- Use `CREDENTIALS_CONFIG` instead of `SERVICE_ACCOUNT_PATH` inside Docker to avoid mounting secrets as files.\n- The container starts with `--transport sse` and listens on `HOST`\u002F`PORT`. Point your MCP client to `http:\u002F\u002Flocalhost:8000` using SSE transport.\n\n---\n\n## 🔌 Usage with Claude Desktop\n\nAdd the server config to `claude_desktop_config.json` under `mcpServers`. Choose the block matching your setup:\n\n_Refer to the [ID Reference Guide](#-id-reference-guide) for more information about the IDs used below._\n\n**⚠️ Important Notes:**\n- **🍎 macOS Users:** use the full path: `\"\u002FUsers\u002Fyourusername\u002F.local\u002Fbin\u002Fuvx\"` instead of just `\"uvx\"`\n\n\u003Cdetails>\n\u003Csummary>🔵 Config: uvx + Service Account (Recommended)\u003C\u002Fsummary>\n\n```json\n{\n \"mcpServers\": {\n \"google-sheets\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-google-sheets@latest\"],\n \"env\": {\n \"SERVICE_ACCOUNT_PATH\": \"\u002Ffull\u002Fpath\u002Fto\u002Fyour\u002Fservice-account-key.json\",\n \"DRIVE_FOLDER_ID\": \"your_shared_folder_id_here\"\n }\n }\n }\n}\n```\n\n**🍎 macOS Note:** If you get a `spawn uvx ENOENT` error, use the full path to `uvx`:\n```json\n{\n \"mcpServers\": {\n \"google-sheets\": {\n \"command\": \"\u002FUsers\u002Fyourusername\u002F.local\u002Fbin\u002Fuvx\",\n \"args\": [\"mcp-google-sheets@latest\"],\n \"env\": {\n \"SERVICE_ACCOUNT_PATH\": \"\u002Ffull\u002Fpath\u002Fto\u002Fyour\u002Fservice-account-key.json\",\n \"DRIVE_FOLDER_ID\": \"your_shared_folder_id_here\"\n }\n }\n }\n}\n```\n*Replace `yourusername` with your actual username.*\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>🔵 Config: uvx + OAuth 2.0\u003C\u002Fsummary>\n\n```json\n{\n \"mcpServers\": {\n \"google-sheets\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-google-sheets@latest\"],\n \"env\": {\n \"CREDENTIALS_PATH\": \"\u002Ffull\u002Fpath\u002Fto\u002Fyour\u002Fcredentials.json\",\n \"TOKEN_PATH\": \"\u002Ffull\u002Fpath\u002Fto\u002Fyour\u002Ftoken.json\"\n }\n }\n }\n}\n```\n*Note: A browser may open for Google login on first use. Ensure TOKEN_PATH is writable.*\n\n**🍎 macOS Note:** If you get a `spawn uvx ENOENT` error, replace `\"command\": \"uvx\"` with `\"command\": \"\u002FUsers\u002Fyourusername\u002F.local\u002Fbin\u002Fuvx\"` (replace `yourusername` with your actual username).\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>🔵 Config: uvx + CREDENTIALS_CONFIG (Service Account Example)\u003C\u002Fsummary>\n\n```json\n{\n \"mcpServers\": {\n \"google-sheets\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-google-sheets@latest\"],\n \"env\": {\n \"CREDENTIALS_CONFIG\": \"ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAi...\",\n \"DRIVE_FOLDER_ID\": \"your_shared_folder_id_here\"\n }\n }\n }\n}\n```\n*Note: Paste the full Base64 string for CREDENTIALS_CONFIG. DRIVE_FOLDER_ID is still needed for Service Account folder context.*\n\n**🍎 macOS Note:** If you get a `spawn uvx ENOENT` error, replace `\"command\": \"uvx\"` with `\"command\": \"\u002FUsers\u002Fyourusername\u002F.local\u002Fbin\u002Fuvx\"` (replace `yourusername` with your actual username).\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>🔵 Config: uvx + Application Default Credentials (ADC)\u003C\u002Fsummary>\n\n**Option 1: With GOOGLE_APPLICATION_CREDENTIALS**\n```json\n{\n \"mcpServers\": {\n \"google-sheets\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-google-sheets@latest\"],\n \"env\": {\n \"GOOGLE_APPLICATION_CREDENTIALS\": \"\u002Fpath\u002Fto\u002Fservice-account.json\"\n }\n }\n }\n}\n```\n\n**Option 2: With gcloud auth (no env vars needed)**\n```json\n{\n \"mcpServers\": {\n \"google-sheets\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-google-sheets@latest\"],\n \"env\": {}\n }\n }\n}\n```\n*Prerequisites:* \n1. *Run `gcloud auth application-default login --scopes=https:\u002F\u002Fwww.googleapis.com\u002Fauth\u002Fcloud-platform,https:\u002F\u002Fwww.googleapis.com\u002Fauth\u002Fspreadsheets,https:\u002F\u002Fwww.googleapis.com\u002Fauth\u002Fdrive` first.*\n2. *Set quota project: `gcloud auth application-default set-quota-project \u003Cproject_id>`*\n\n**🍎 macOS Note:** If you get a `spawn uvx ENOENT` error, replace `\"command\": \"uvx\"` with `\"command\": \"\u002FUsers\u002Fyourusername\u002F.local\u002Fbin\u002Fuvx\"` (replace `yourusername` with your actual username).\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>🟡 Config: Development (Running from cloned repo)\u003C\u002Fsummary>\n\n```json\n{\n \"mcpServers\": {\n \"mcp-google-sheets-local\": {\n \"command\": \"uv\",\n \"args\": [\n \"run\",\n \"--directory\",\n \"\u002Fpath\u002Fto\u002Fyour\u002Fmcp-google-sheets\",\n \"mcp-google-sheets\"\n ],\n \"env\": {\n \"SERVICE_ACCOUNT_PATH\": \"\u002Fpath\u002Fto\u002Fyour\u002Fmcp-google-sheets\u002Fservice_account.json\",\n \"DRIVE_FOLDER_ID\": \"your_drive_folder_id_here\"\n }\n }\n }\n}\n```\n*Note: Use `--directory` flag to specify the project path, and adjust paths to match your actual workspace location.*\n\u003C\u002Fdetails>\n\n---\n\n## 💬 Example Prompts for Claude\n\nOnce connected, try prompts like:\n\n* \"List all spreadsheets I have access to.\" (or \"in my AI Managed Sheets folder\")\n* \"Create a new spreadsheet titled 'Quarterly Sales Report Q3 2024'.\"\n* \"In the 'Quarterly Sales Report' spreadsheet, get the data from Sheet1 range A1 to E10.\"\n* \"Add a new sheet named 'Summary' to the spreadsheet with ID `1aBcDeFgHiJkLmNoPqRsTuVwXyZ`.\"\n* \"In my 'Project Tasks' spreadsheet, Sheet 'Tasks', update cell B2 to 'In Progress'.\"\n* \"Append these rows to the 'Log' sheet in spreadsheet `XYZ`: `[['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']]`\"\n* \"Get a summary of the spreadsheets 'Sales Data' and 'Inventory Count'.\"\n* \"Share the 'Team Vacation Schedule' spreadsheet with `team@example.com` as a reader and `manager@example.com` as a writer. Don't send notifications.\"\n* \"Create a column chart in my 'Sales Report' spreadsheet showing monthly revenue from data in range A1:B13.\"\n* \"Add a pie chart to the 'Market Analysis' sheet with data from A1:B5 titled 'Market Share by Product'.\"\n* \"In spreadsheet `abc123`, create a line chart on Sheet1 from range A1:C10 with title 'Growth Trends' and labels 'Month' and 'Revenue'.\"\n\n---\n\n## 🆔 ID Reference Guide\n\nUse the following reference guide to find the various IDs referenced throughout the docs:\n\n```\nGoogle Cloud Project ID:\n https:\u002F\u002Fconsole.cloud.google.com\u002Fapis\u002Fdashboard?project=sheets-mcp-server-123456\n └───── Project ID ─────┘\n\nGoogle Drive Folder ID:\n https:\u002F\u002Fdrive.google.com\u002Fdrive\u002Fu\u002F0\u002Ffolders\u002F1xcRQCU9xrNVBPTeNzHqx4hrG7yR91WIa\n └────────── Folder ID ──────────┘\n\nGoogle Sheets Spreadsheet ID:\n https:\u002F\u002Fdocs.google.com\u002Fspreadsheets\u002Fd\u002F25_-_raTaKjaVxu9nJzA7-FCrNhnkd3cXC54BPAOXemI\u002Fedit\n └───────────── Spreadsheet ID ─────────────┘\n```\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please open an issue to discuss bugs or feature requests. Pull requests are appreciated.\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🙏 Credits\n\n* Built with [FastMCP](https:\u002F\u002Fgithub.com\u002Fcognitiveapis\u002Ffastmcp).\n* Inspired by [kazz187\u002Fmcp-google-spreadsheet](https:\u002F\u002Fgithub.com\u002Fkazz187\u002Fmcp-google-spreadsheet).\n* Uses Google API Python Client libraries.\n","\u003Cdiv align=\"center\">\n \u003C!-- 主标题链接 -->\n \u003Cb>mcp-google-sheets\u003C\u002Fb>\n\n \u003C!-- 描述段落 -->\n \u003Cp align=\"center\">\n \u003Ci>您的 AI 助手通往 Google 表格的入口！\u003C\u002Fi>📊\n \u003C\u002Fp>\n\n[![PyPI - 版本](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fmcp-google-sheets)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fmcp-google-sheets\u002F)\n[![PyPI 下载量](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fxing5_mcp-google-sheets_readme_a397c9b5ce36.png)](https:\u002F\u002Fpepy.tech\u002Fprojects\u002Fmcp-google-sheets)\n![GitHub 许可证](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fxing5\u002Fmcp-google-sheets)\n![GitHub Actions 工作流状态](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Factions\u002Fworkflow\u002Fstatus\u002Fxing5\u002Fmcp-google-sheets\u002Frelease.yml)\n\u003C\u002Fdiv>\n\n---\n\n## 🤔 这是什么？\n\n`mcp-google-sheets` 是一个基于 Python 的 MCP 服务器，充当任何兼容 MCP 的客户端（如 Claude Desktop）与 Google Sheets API 之间的桥梁。它允许您使用一组预定义的工具与 Google 表格进行交互，从而实现由 AI 驱动的强大自动化和数据处理工作流。\n\n---\n\n## 🚀 快速入门（使用 `uvx`）\n\n本质上，服务器只需一行命令即可运行：`uvx mcp-google-sheets@latest`。\n\n该命令会自动下载最新代码并运行。**我们建议始终使用 `@latest`**，以确保您拥有包含最新功能和错误修复的最新版本。\n\n_请参阅 [ID 参考指南](#-id-reference-guide) 以获取有关下方使用的 ID 的更多信息。_\n\n1. **☁️ 前提条件：Google Cloud 设置**\n * 您**必须**先配置 Google Cloud Platform 凭据并启用必要的 API。我们强烈建议使用**服务账号**。\n * ➡️ 请跳转至下方的 [**Google Cloud Platform 详细设置**](#-google-cloud-platform-setup-detailed) 指南。\n\n2. **🐍 安装 `uv`**\n * `uvx` 是 `uv` 的一部分，`uv` 是一个快速的 Python 包管理器和解析器。如果您尚未安装，请执行以下操作：\n ```bash\n # macOS \u002F Linux\n curl -LsSf https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.sh | sh\n # Windows\n powershell -c \"irm https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.ps1 | iex\"\n # 或者使用 pip：\n # pip install uv\n ```\n *根据安装程序输出中的说明，将 `uv` 添加到您的 PATH 中（如果需要）。*\n\n3. **🔑 设置必要的环境变量（推荐使用服务账号）**\n * 您需要告知服务器如何进行身份验证。在终端中设置以下变量：\n * **(Linux\u002FmacOS)**\n ```bash\n # 替换为您实际的路径和来自 Google 设置步骤的文件夹 ID\n export SERVICE_ACCOUNT_PATH=\"\u002Fpath\u002Fto\u002Fyour\u002Fservice-account-key.json\"\n export DRIVE_FOLDER_ID=\"YOUR_DRIVE_FOLDER_ID\"\n ```\n * **(Windows CMD)**\n ```cmd\n set SERVICE_ACCOUNT_PATH=\"C:\\path\\to\\your\\service-account-key.json\"\n set DRIVE_FOLDER_ID=\"YOUR_DRIVE_FOLDER_ID\"\n ```\n * **(Windows PowerShell)**\n ```powershell\n $env:SERVICE_ACCOUNT_PATH = \"C:\\path\\to\\your\\service-account-key.json\"\n $env:DRIVE_FOLDER_ID = \"YOUR_DRIVE_FOLDER_ID\"\n ```\n * ➡️ 请参阅 [**身份验证与环境变量详细说明**](#-authentication--environment-variables-detailed) 以了解其他选项（OAuth、`CREDENTIALS_CONFIG`）。\n\n4. **🏃 启动服务器！**\n * `uvx` 会自动下载并运行最新版本的 `mcp-google-sheets`：\n ```bash\n uvx mcp-google-sheets@latest\n ```\n * 服务器将启动，并打印日志表明已准备就绪。\n * \n * > **💡 小贴士：** 始终使用 `@latest` 以确保获得包含错误修复和新功能的最新版本。如果不使用 `@latest`，`uvx` 可能会使用缓存的旧版本。\n\n5. **🔌 连接您的 MCP 客户端**\n * 配置您的客户端（例如 Claude Desktop）以连接到正在运行的服务器。\n * 根据您使用的客户端，可能不需要第 4 步，因为客户端可以为您启动服务器。不过，最好还是按照第 4 步测试运行一下，以确保一切设置正确。\n * ➡️ 请参阅 [**与 Claude Desktop 的使用方法**](#-usage-with-claude-desktop) 以获取示例。\n\n6. **⚡ 可选：启用工具过滤（减少上下文使用）**\n * 默认情况下，所有 19 个工具均被启用（约 13K 个标记）。为了减少上下文使用，您可以仅启用所需的工具。\n * ➡️ 请参阅 [**工具过滤：减少上下文使用**](#-tool-filtering-reduce-context-usage) 以获取详细信息。\n\n现在您已经准备就绪！可以通过您的 MCP 客户端开始发出命令了。\n\n---\n\n## ✨ 核心特性\n\n* **无缝集成：** 直接连接到 Google Drive 和 Google Sheets API。\n* **全面的工具集：** 提供广泛的操作功能（CRUD、列出、批量处理、共享、格式化等）。\n* **灵活的身份验证：** 支持**服务账号（推荐）**、OAuth 2.0，以及通过环境变量直接注入凭据。\n* **轻松部署：** 使用 `uvx` 即时运行（无需安装），或使用 `uv` 克隆以进行开发。\n* **AI 就绪：** 专为与 MCP 兼容的客户端一起使用而设计，支持自然语言的表格交互。\n* **工具过滤：** 通过 `--include-tools` 或 `ENABLED_TOOLS` 环境变量，仅启用您需要的工具，从而减少上下文窗口的使用。\n\n---\n\n## 🎯 工具过滤（减少上下文使用）\n\n**问题：** 默认情况下，此 MCP 服务器会暴露全部 19 个工具，这会在任何对话开始之前消耗约 13,000 个标记。如果您只需要几个工具，这将浪费宝贵的上下文窗口空间。\n\n**解决方案：** 使用工具过滤功能，仅启用您实际使用的工具。\n\n### 如何启用工具过滤\n\n您可以通过以下两种方式之一来过滤工具：\n\n1. **命令行参数** `--include-tools`：\n ```json\n {\n \"mcpServers\": {\n \"google-sheets\": {\n \"command\": \"uvx\",\n \"args\": [\n \"mcp-google-sheets@latest\",\n \"--include-tools\",\n \"get_sheet_data,update_cells,list_spreadsheets,list_sheets\"\n ],\n \"env\": {\n \"SERVICE_ACCOUNT_PATH\": \"\u002Fpath\u002Fto\u002Fcredentials.json\"\n }\n }\n }\n }\n ```\n\n2. **环境变量** `ENABLED_TOOLS`：\n ```json\n {\n \"mcpServers\": {\n \"google-sheets\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-google-sheets@latest\"],\n \"env\": {\n \"SERVICE_ACCOUNT_PATH\": \"\u002Fpath\u002Fto\u002Fcredentials.json\",\n \"ENABLED_TOOLS\": \"get_sheet_data,update_cells,list_spreadsheets,list_sheets\"\n }\n }\n }\n }\n ```\n\n### 可用工具名称\n\n在筛选时，请使用这些精确的工具名称（以逗号分隔，不含空格）：\n\n**最常用工具（推荐子集）：**\n- `get_sheet_data` - 从电子表格中读取数据\n- `update_cells` - 向电子表格中写入数据\n- `list_spreadsheets` - 查找电子表格\n- `list_sheets` - 浏览工作表标签\n\n**所有可用工具：**\n- `add_columns`\n- `add_rows`\n- `batch_update`\n- `batch_update_cells`\n- `copy_sheet`\n- `create_sheet`\n- `create_spreadsheet`\n- `find_in_spreadsheet`\n- `get_multiple_sheet_data`\n- `get_multiple_spreadsheet_summary`\n- `get_sheet_data`\n- `get_sheet_formulas`\n- `list_folders`\n- `list_sheets`\n- `list_spreadsheets`\n- `rename_sheet`\n- `search_spreadsheets`\n- `share_spreadsheet`\n- `update_cells`\n\n**注意：** 如果既未指定 `--include-tools` 也未设置 `ENABLED_TOOLS`，则所有工具都将被启用（默认行为）。\n\n---\n\n## 🛠️ 可用工具与资源\n\n本服务器公开了以下用于与 Google 电子表格交互的工具：\n\n_有关下方使用的 ID 的更多信息，请参阅 [ID 参考指南](#-id-reference-guide)。_\n\n*（输入参数通常为字符串，除非另有说明）*\n\n* **`list_spreadsheets`**: 列出配置的 Drive 文件夹（服务账号）中的电子表格，或当前用户（OAuth）可访问的电子表格。\n * `folder_id`（可选字符串）：要在其中搜索的 Google Drive 文件夹 ID。从其 URL 中获取。如果省略，则使用配置的默认文件夹，或在“我的云端硬盘”中搜索。\n * _返回值:_ 对象列表 `[{id: string, title: string}]`\n* **`create_spreadsheet`**: 创建一个新的电子表格。\n * `title`（字符串）：电子表格的期望标题。例如：“第四季度报告”。\n * `folder_id`（可选字符串）：应在其中创建电子表格的 Google Drive 文件夹 ID。从其 URL 中获取。如果省略，则使用配置的默认文件夹或根目录。\n * _返回值:_ 包含电子表格信息的对象，包括 `spreadsheetId`、`title` 和 `folder`。\n* **`get_sheet_data`**: 读取工作表\u002F标签页中某个区域的数据。\n * `spreadsheet_id`（字符串）：电子表格 ID（从其 URL 中获取）。\n * `sheet`（字符串）：工作表\u002F标签页的名称（例如：“Sheet1”）。\n * `range`（可选字符串）：A1 表示法（例如：“A1:C10”、“Sheet1!B2:D”）。如果省略，则读取由 `sheet` 指定的工作表\u002F标签页的全部内容。\n * `include_grid_data`（可选布尔值，默认为 `False`）：如果为 `True`，则返回包含格式和元数据的完整网格数据（数据量较大）。如果为 `False`，则仅返回值（效率更高）。\n * _返回值:_ 如果 `include_grid_data=True`，则返回包含元数据的完整网格数据（[`get` 响应](https:\u002F\u002Fdevelopers.google.com\u002Fworkspace\u002Fsheets\u002Fapi\u002Freference\u002Frest\u002Fv4\u002Fspreadsheets\u002Fget#response-body)）。如果为 `False`，则返回 Values API 的值结果对象（[`values.get` 响应](https:\u002F\u002Fdevelopers.google.com\u002Fworkspace\u002Fsheets\u002Fapi\u002Freference\u002Frest\u002Fv4\u002Fspreadsheets.values\u002Fget#response-body)）。\n* **`get_sheet_formulas`**: 读取工作表\u002F标签页中某个区域的公式。\n * `spreadsheet_id`（字符串）：电子表格 ID（从其 URL 中获取）。\n * `sheet`（字符串）：工作表\u002F标签页的名称（例如：“Sheet1”）。\n * `range`（可选字符串）：A1 表示法（例如：“A1:C10”、“Sheet1!B2:D”）。如果省略，则读取由 `sheet` 指定的工作表\u002F标签页中的所有公式。\n * _返回值:_ 单元格公式的二维数组（数组的数组）（[`values.get` 响应](https:\u002F\u002Fdevelopers.google.com\u002Fworkspace\u002Fsheets\u002Fapi\u002Freference\u002Frest\u002Fv4\u002Fspreadsheets.values\u002Fget#response-body)）。\n* **`update_cells`**: 将数据写入特定范围。会覆盖现有数据。\n * `spreadsheet_id`（字符串）：电子表格 ID（从其 URL 中获取）。\n * `sheet`（字符串）：工作表\u002F标签页的名称（例如：“Sheet1”）。\n * `range`（字符串）：要写入的 A1 表示法范围（例如：“A1:C3”）。\n * `data`（数组的数组）：要写入的二维值数组。例如：`[[1, 2, 3], [\"a\", \"b\", \"c\"]]`。\n * _返回值:_ 更新结果对象（[`values.update` 响应](https:\u002F\u002Fdevelopers.google.com\u002Fworkspace\u002Fsheets\u002Fapi\u002Freference\u002Frest\u002Fv4\u002Fspreadsheets.values\u002Fupdate#response-body)）。\n* **`batch_update_cells`**: 在一次 API 调用中更新多个范围。\n * `spreadsheet_id`（字符串）：电子表格 ID（从其 URL 中获取）。\n * `sheet`（字符串）：工作表\u002F标签页的名称（例如：“Sheet1”）。\n * `ranges`（对象）：将范围字符串（A1 表示法）映射到值的二维数组。例如：`{ \"A1:B2\": [[1, 2], [3, 4]], \"D5\": [[\"Hello\"]] }`。\n * _返回值:_ 操作结果（[`values.batchUpdate` 响应](https:\u002F\u002Fdevelopers.google.com\u002Fworkspace\u002Fsheets\u002Fapi\u002Freference\u002Frest\u002Fv4\u002Fspreadsheets.values\u002FbatchUpdate#response-body)）。\n* **`add_rows`**: 在指定索引处向工作表\u002F标签页添加（插入）空行。\n * `spreadsheet_id`（字符串）：电子表格 ID（从其 URL 中获取）。\n * `sheet`（字符串）：工作表\u002F标签页的名称（例如：“Sheet1”）。\n * `count`（整数）：要插入的空行数量。\n * `start_row`（可选整数，默认为 `0`）：基于 0 的行索引，用于开始插入行。如果省略，则默认为 `0`（在开头插入）。\n * _返回值:_ 操作结果（[`batchUpdate` 响应](https:\u002F\u002Fdevelopers.google.com\u002Fworkspace\u002Fsheets\u002Fapi\u002Freference\u002Frest\u002Fv4\u002Fspreadsheets\u002FbatchUpdate#response-body)）。\n* **`list_sheets`**: 列出电子表格中的所有工作表\u002F标签页名称。\n * `spreadsheet_id`（字符串）：电子表格 ID（从其 URL 中获取）。\n * _返回值:_ 工作表\u002F标签页名称字符串列表。例如：`[\"Sheet1\", \"Sheet2\"]`。\n* **`create_sheet`**: 向电子表格添加新的工作表\u002F标签页。\n * `spreadsheet_id`（字符串）：电子表格 ID（从其 URL 中获取）。\n * `title`（字符串）：新工作表\u002F标签页的名称。\n * _返回值:_ 新工作表属性对象。\n* **`get_multiple_sheet_data`**: 在一次调用中从可能不同的电子表格中的多个范围获取数据。\n * `queries`（对象数组）：每个对象需要 `spreadsheet_id`、`sheet` 和 `range`。例如：`[{\"spreadsheet_id\": \"abc\", \"sheet\": \"Sheet1\", \"range\": \"A1:B2\"}, ...]`。\n * _返回值:_ 对象列表，每个对象包含查询参数和获取到的 `data` 或 `error`。每份 `data` 都是 [`values.get` 响应](https:\u002F\u002Fdevelopers.google.com\u002Fworkspace\u002Fsheets\u002Fapi\u002Freference\u002Frest\u002Fv4\u002Fspreadsheets.values\u002Fget#response-body)。\n* **`get_multiple_spreadsheet_summary`**: 获取多个电子表格的标题、工作表\u002F标签页名称、表头以及前几行数据。\n * `spreadsheet_ids`（字符串数组）：电子表格的 ID（从其 URLs 中获取）。\n * `rows_to_fetch`（可选整数，默认为 `5`）：预览多少行数据（包括表头）。例如：`5`。\n * _返回值:_ 每个电子表格的摘要对象列表。\n* **`share_spreadsheet`**: 将电子表格与指定用户\u002F邮箱及角色共享。\n * `spreadsheet_id`（字符串）：电子表格 ID（从其 URL 中获取）。\n * `recipients`（对象数组）：`[{\"email_address\": \"user@example.com\", \"role\": \"writer\"}, ...]`。角色包括：`reader`、`commenter`、`writer`。\n * `send_notification`（可选布尔值，默认为 `True`）：是否向收件人发送电子邮件通知。\n * _返回值:_ 包含成功和失败列表的字典。\n* **`add_columns`**: 在指定索引处向工作表\u002F标签页添加（插入）空列。\n * `spreadsheet_id`（字符串）：电子表格 ID（从其 URL 中获取）。\n * `sheet`（字符串）：工作表\u002F标签页的名称（例如：“Sheet1”）。\n * `count`（整数）：要插入的空列数量。\n * `start_column`（可选整数，默认为 `0`）：基于 0 的列索引，用于开始插入。如果省略，则默认为 `0`（在开头插入）。\n * _返回值:_ 操作结果（[`batchUpdate` 响应](https:\u002F\u002Fdevelopers.google.com\u002Fworkspace\u002Fsheets\u002Fapi\u002Freference\u002Frest\u002Fv4\u002Fspreadsheets\u002FbatchUpdate#response-body)）。\n* **`copy_sheet`**: 将一个工作表\u002F标签页从一个电子表格复制到另一个，并可选择重命名。\n * `src_spreadsheet`（字符串）：源电子表格 ID（从其 URL 中获取）。\n * `src_sheet`（字符串）：源工作表\u002F标签页名称（例如：“Sheet1”）。\n * `dst_spreadsheet`（字符串）：目标电子表格 ID（从其 URL 中获取）。\n * `dst_sheet`（字符串）：目标电子表格中希望的新工作表\u002F标签页名称。\n * _返回值:_ 复制及可选重命名操作的结果。\n* **`rename_sheet`**: 重命名现有的工作表\u002F标签页。\n * `spreadsheet`（字符串）：电子表格 ID（从其 URL 中获取）。\n * `sheet`（字符串）：当前工作表\u002F标签页名称（例如：“Sheet1”）。\n * `new_name`（字符串）：新的工作表\u002F标签页名称（例如：“Transactions”）。\n * _返回值:_ 操作结果（[`batchUpdate` 响应](https:\u002F\u002Fdevelopers.google.com\u002Fworkspace\u002Fsheets\u002Fapi\u002Freference\u002Frest\u002Fv4\u002Fspreadsheets\u002FbatchUpdate#response-body)）。\n* **`add_chart`**: 根据指定数据在 Google 表格中创建图表。\n * `spreadsheet_id`（字符串）：电子表格 ID（从其 URL 中获取）。\n * `sheet`（字符串）：包含数据的工作表\u002F标签页名称（例如：“Sheet1”）。\n * `chart_type`（字符串）：要创建的图表类型。选项包括：`COLUMN`（垂直柱状图）、`BAR`（水平柱状图）、`LINE`、`AREA`、`PIE`、`SCATTER`、`COMBO`、`HISTOGRAM`。\n * `data_range`（字符串）：用于图表数据的 A1 表示法范围（例如：“A1:C10”）。第一行被视为表头。\n * `title`（可选字符串）：图表标题。\n * `x_axis_label`（可选字符串）：X 轴（底部轴）的标签。不适用于饼图。\n * `y_axis_label`（可选字符串）：Y 轴（左侧轴）的标签。不适用于饼图。\n * `position_x`（可选整数，默认为 `0`）：从左上角开始的水平偏移像素数。\n * `position_y`（可选整数，默认为 `0`）：从左上角开始的垂直偏移像素数。\n * `width`（可选整数，默认为 `600`）：图表的宽度（以像素为单位）。\n * `height`（可选整数，默认为 `400`）：图表的高度（以像素为单位）。\n * _返回值:_ 包含成功状态、图表 ID 和操作详情的结果对象。\n\n**MCP 资源：**\n\n* **`spreadsheet:\u002F\u002F{spreadsheet_id}\u002Finfo`**: 获取 Google 表格的基本元数据。\n * _返回:_ 包含表格信息的 JSON 字符串。\n\n---\n\n\n\n## ☁️ Google Cloud Platform 设置（详细）\n\n在运行服务器之前，此设置是**必需**的。\n\n1. **创建或选择 GCP 项目:** 前往 [Google Cloud 控制台](https:\u002F\u002Fconsole.cloud.google.com\u002F)。\n2. **启用 API:** 导航到“API 和服务”->“库”。搜索并启用：\n * `Google Sheets API`\n * `Google Drive API`\n3. **配置凭据:** 您需要从以下方法中选择*一种*身份验证方式（推荐使用服务账户）。\n\n---\n\n## 🔑 身份验证与环境变量（详细）\n\n服务器需要凭据才能访问 Google API。请选择一种方法：\n\n_有关下方使用的 ID 的更多信息，请参阅[ID 参考指南](#-id-reference-guide)。_\n\n### 方法 A：服务账户（推荐用于服务器\u002F自动化）✅\n\n* **为什么？** 无头模式（无需浏览器），安全，非常适合服务器环境。不易过期。\n* **步骤：**\n 1. **创建服务账户:** 在 GCP 控制台 -> “IAM 和管理员” -> “服务账户”。\n * 点击“+ 创建服务账户”。为其命名（例如 `mcp-sheets-service`）。\n * 授予角色：添加 `编辑者` 角色以获得广泛权限，或更细粒度的角色（如 `roles\u002Fdrive.file` 和特定的 Sheets 角色）以获得更严格的权限。\n * 点击“完成”。找到该账户，点击操作按钮 (⋮) -> “管理密钥”。\n * 点击“添加密钥” -> “创建新密钥” -> **JSON** -> “创建”。\n * **下载并安全存储** JSON 密钥文件。\n 2. **创建并共享 Google 云端硬盘文件夹:**\n * 在 [Google 云端硬盘](https:\u002F\u002Fdrive.google.com\u002F) 中，创建一个文件夹（例如“AI Managed Sheets”）。\n * 从 URL 中记下**文件夹 ID**: `https:\u002F\u002Fdrive.google.com\u002Fdrive\u002Ffolders\u002FTHIS_IS_THE_FOLDER_ID`。\n * 右键单击该文件夹 -> “共享” -> “共享”。\n * 输入服务账户的电子邮件地址（来自 JSON 文件中的 `client_email`）。\n * 授予**编辑者**权限。取消选中“通知用户”。点击“共享”。\n 3. **设置环境变量:**\n * `SERVICE_ACCOUNT_PATH`: 下载的 JSON 密钥文件的完整路径。\n * `DRIVE_FOLDER_ID`: 共享 Google 云端硬盘文件夹的 ID。\n *(请参阅 [超快速入门](#-ultra-quick-start-using-uvx) 以获取各操作系统的具体示例)*\n\n### 方法 B：OAuth 2.0（交互式\u002F个人使用）🧑‍💻\n\n* **为什么？** 适用于个人使用或本地开发，在这种情况下，交互式浏览器登录是可以接受的。\n* **步骤：**\n 1. **配置 OAuth 同意屏幕:** 在 GCP 控制台 -> “API 和服务” -> “OAuth 同意屏幕”。选择“外部”，填写所需信息，添加范围（`...\u002Fauth\u002Fspreadsheets`、`...\u002Fauth\u002Fdrive`），如有必要，添加测试用户。\n 2. **创建 OAuth 客户端 ID:** 在 GCP 控制台 -> “API 和服务” -> “凭据”。点击“+ 创建凭据” -> “OAuth 客户端 ID” -> 类型：**桌面应用**。为其命名。“创建”。**下载 JSON**。\n 3. **设置环境变量:**\n * `CREDENTIALS_PATH`: 下载的 OAuth 凭据 JSON 文件的路径（默认为 `credentials.json`）。\n * `TOKEN_PATH`: 存储首次登录后用户刷新令牌的路径（默认为 `token.json`）。必须可写。\n\n### 方法 C：直接注入凭据（高级）🔒\n\n* **为什么？** 适用于 Docker、Kubernetes 或 CI\u002FCD 等环境中，这些环境难以管理文件，但易于\u002F安全地管理环境变量。避免了对文件系统的访问。\n* **如何？** 不再提供凭据文件的*路径*，而是将文件的*内容*以 Base64 编码的形式直接放入环境变量中。\n* **步骤：**\n 1. **获取您的凭据 JSON 文件**（可以是服务账户密钥文件或 OAuth 客户端 ID 文件）。我们将其称为 `your_credentials.json`。\n 2. **生成 Base64 字符串:**\n * **(Linux\u002FmacOS):** `base64 -w 0 your_credentials.json`\n * **(Windows PowerShell):**\n ```powershell\n $filePath = \"C:\\path\\to\\your_credentials.json\"; # 使用实际路径\n $bytes = [System.IO.File]::ReadAllBytes($filePath);\n $base64 = [System.Convert]::ToBase64String($bytes);\n $base64 # 复制此输出\n ```\n * **注意：** 避免将敏感凭据粘贴到不可信的在线编码器中。\n 3. **设置环境变量:**\n * `CREDENTIALS_CONFIG`: 将此变量设置为您刚刚生成的**完整的 Base64 字符串**。\n ```bash\n # 示例（Linux\u002FmacOS）- 使用实际生成的字符串\n export CREDENTIALS_CONFIG=\"ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb...\"\n ```\n\n### 方法 D：应用程序默认凭据（ADC）🌐\n\n* **为什么？** 非常适合 Google Cloud 环境（GKE、Compute Engine、Cloud Run）以及使用 `gcloud auth application-default login` 进行本地开发。无需显式凭据文件。\n* **如何？** 使用 Google 的应用程序默认凭据链自动从多个来源发现凭据。\n* **ADC 搜索顺序：**\n 1. `GOOGLE_APPLICATION_CREDENTIALS` 环境变量（服务账户密钥路径）——**Google 的标准变量**\n 2. `gcloud auth application-default login` 凭据（本地开发）\n 3. 附加到元数据服务器的服务账户（GKE、Compute Engine 等）\n* **设置：**\n * **本地开发：**\n 1. 运行一次 `gcloud auth application-default login --scopes=https:\u002F\u002Fwww.googleapis.com\u002Fauth\u002Fcloud-platform,https:\u002F\u002Fwww.googleapis.com\u002Fauth\u002Fspreadsheets,https:\u002F\u002Fwww.googleapis.com\u002Fauth\u002Fdrive`\n 2. 设置配额项目：`gcloud auth application-default set-quota-project \u003Cproject_id>`（将 `\u003Cproject_id>` 替换为您的 Google Cloud 项目 ID）\n * **Google Cloud：** 将服务账户附加到您的计算资源上\n * **环境变量：** 设置 `GOOGLE_APPLICATION_CREDENTIALS=\u002Fpath\u002Fto\u002Fservice-account.json`（Google 的标准）\n* **无需额外的环境变量**——当其他方法失败时，ADC 会自动用作后备。\n\n**注意：** `GOOGLE_APPLICATION_CREDENTIALS` 是 Google 的官方标准环境变量，而 `SERVICE_ACCOUNT_PATH` 则是此 MCP 服务器特有的。如果您设置了 `GOOGLE_APPLICATION_CREDENTIALS`，ADC 会自动找到它。\n\n### 身份验证优先级与摘要\n\n服务器会按以下顺序检查凭据：\n\n1. `CREDENTIALS_CONFIG`（Base64 编码的内容）\n2. `SERVICE_ACCOUNT_PATH`（服务帐号 JSON 文件的路径）\n3. `CREDENTIALS_PATH`（OAuth JSON 文件的路径）——如果令牌缺失或已过期，则触发交互式流程\n4. **应用默认凭据 (ADC)**——自动回退\n\n**环境变量摘要：**\n\n| 变量 | 方法 | 描述 | 默认值 |\n|:---------------------------------|:----------------------------|:-----------------------------------------------------------------|:-------------------|\n| `SERVICE_ACCOUNT_PATH` | 服务帐号 | 服务帐号 JSON 密钥文件的路径（MCP 服务器专用）。 | - |\n| `GOOGLE_APPLICATION_CREDENTIALS` | ADC | 服务帐号密钥的路径（Google 的标准环境变量）。 | - |\n| `DRIVE_FOLDER_ID` | 服务帐号 | 与服务帐号共享的 Google 云端硬盘文件夹 ID。 | - |\n| `CREDENTIALS_PATH` | OAuth 2.0 | OAuth 2.0 客户端 ID JSON 文件的路径。 | `credentials.json` |\n| `TOKEN_PATH` | OAuth 2.0 | 用于存储生成的 OAuth 令牌的路径。 | `token.json` |\n| `CREDENTIALS_CONFIG` | 服务帐号 \u002F OAuth 2.0 | 凭据内容的 Base64 编码 JSON 字符串。 | - |\n\n---\n\n## ⚙️ 运行服务器（详细说明）\n\n_有关下方使用的 ID 的更多信息，请参阅 [ID 参考指南](#-id-reference-guide)。_\n\n### 方法 1：使用 `uvx`（推荐给用户）\n\n如[超快速入门](#-ultra-quick-start-using-uvx)所示，这是最简单的方式。设置环境变量后，运行以下命令：\n\n```bash\nuvx mcp-google-sheets@latest\n```\n`uvx` 会临时获取并运行该包。\n\n### 方法 2：用于开发（克隆仓库）\n\n如果您想修改代码：\n\n1. **克隆：** `git clone https:\u002F\u002Fgithub.com\u002Fyourusername\u002Fmcp-google-sheets.git && cd mcp-google-sheets`（请使用实际 URL）\n2. **设置环境变量：** 如上所述。\n3. **使用 `uv` 运行：** （使用本地代码）\n ```bash\n uv run mcp-google-sheets\n # 或者通过 pyproject.toml 中定义的脚本名称运行，例如：\n # uv run start\n ```\n\n### 方法 3：Docker（SSE 传输）\n\n使用附带的 `Dockerfile` 在容器中运行服务器：\n\n```bash\n# 构建镜像\ndocker build -t mcp-google-sheets .\n\n# 运行（SSE 使用 8000 端口）\n# 注意：在容器中建议使用 CREDENTIALS_CONFIG（Base64 编码的凭据内容）。\ndocker run --rm -p 8000:8000 ^\n -e HOST=0.0.0.0 ^\n -e PORT=8000 ^\n -e CREDENTIALS_CONFIG=YOUR_BASE64_CREDENTIALS ^\n -e DRIVE_FOLDER_ID=YOUR_DRIVE_FOLDER_ID ^\n mcp-google-sheets\n```\n\n- 在 Docker 容器内应使用 `CREDENTIALS_CONFIG` 而不是 `SERVICE_ACCOUNT_PATH`，以避免将敏感信息作为文件挂载。\n- 容器启动时会使用 `--transport sse` 并监听 `HOST`\u002F`PORT`。请将您的 MCP 客户端指向 `http:\u002F\u002Flocalhost:8000`，并使用 SSE 传输方式。\n\n---\n\n## 🔌 与 Claude Desktop 的使用\n\n将服务器配置添加到 `claude_desktop_config.json` 文件中的 `mcpServers` 部分。根据你的设置选择相应的配置块：\n\n_请参阅 [ID 参考指南](#-id-reference-guide) 以获取有关以下 ID 的更多信息。_\n\n**⚠️ 重要提示：**\n- **🍎 macOS 用户：** 请使用完整路径：`\"\u002FUsers\u002Fyourusername\u002F.local\u002Fbin\u002Fuvx\"`，而不是仅使用 `\"uvx\"`\n\n\u003Cdetails>\n\u003Csummary>🔵 配置：uvx + 服务账号（推荐）\u003C\u002Fsummary>\n\n```json\n{\n \"mcpServers\": {\n \"google-sheets\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-google-sheets@latest\"],\n \"env\": {\n \"SERVICE_ACCOUNT_PATH\": \"\u002Ffull\u002Fpath\u002Fto\u002Fyour\u002Fservice-account-key.json\",\n \"DRIVE_FOLDER_ID\": \"your_shared_folder_id_here\"\n }\n }\n }\n}\n```\n\n**🍎 macOS 注意：** 如果出现 `spawn uvx ENOENT` 错误，请使用 `uvx` 的完整路径：\n```json\n{\n \"mcpServers\": {\n \"google-sheets\": {\n \"command\": \"\u002FUsers\u002Fyourusername\u002F.local\u002Fbin\u002Fuvx\",\n \"args\": [\"mcp-google-sheets@latest\"],\n \"env\": {\n \"SERVICE_ACCOUNT_PATH\": \"\u002Ffull\u002Fpath\u002Fto\u002Fyour\u002Fservice-account-key.json\",\n \"DRIVE_FOLDER_ID\": \"your_shared_folder_id_here\"\n }\n }\n }\n}\n```\n*请将 `yourusername` 替换为你的实际用户名。*\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>🔵 配置：uvx + OAuth 2.0\u003C\u002Fsummary>\n\n```json\n{\n \"mcpServers\": {\n \"google-sheets\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-google-sheets@latest\"],\n \"env\": {\n \"CREDENTIALS_PATH\": \"\u002Ffull\u002Fpath\u002Fto\u002Fyour\u002Fcredentials.json\",\n \"TOKEN_PATH\": \"\u002Ffull\u002Fpath\u002Fto\u002Fyour\u002Ftoken.json\"\n }\n }\n }\n}\n```\n*注意：首次使用时可能会打开浏览器进行 Google 登录。请确保 `TOKEN_PATH` 是可写的。*\n\n**🍎 macOS 注意：** 如果出现 `spawn uvx ENOENT` 错误，请将 `\"command\": \"uvx\"` 替换为 `\"command\": \"\u002FUsers\u002Fyourusername\u002F.local\u002Fbin\u002Fuvx\"`（将 `yourusername` 替换为你的实际用户名）。\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>🔵 配置：uvx + CREDENTIALS_CONFIG（服务账号示例）\u003C\u002Fsummary>\n\n```json\n{\n \"mcpServers\": {\n \"google-sheets\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-google-sheets@latest\"],\n \"env\": {\n \"CREDENTIALS_CONFIG\": \"ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAi...\",\n \"DRIVE_FOLDER_ID\": \"your_shared_folder_id_here\"\n }\n }\n }\n}\n```\n*注意：请粘贴完整的 Base64 字符串作为 `CREDENTIALS_CONFIG`。对于服务账号的文件夹上下文，仍然需要 `DRIVE_FOLDER_ID`。*\n\n**🍎 macOS 注意：** 如果出现 `spawn uvx ENOENT` 错误，请将 `\"command\": \"uvx\"` 替换为 `\"command\": \"\u002FUsers\u002Fyourusername\u002F.local\u002Fbin\u002Fuvx\"`（将 `yourusername` 替换为你的实际用户名）。\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>🔵 配置：uvx + 应用默认凭据 (ADC)\u003C\u002Fsummary>\n\n**选项 1：使用 GOOGLE_APPLICATION_CREDENTIALS**\n```json\n{\n \"mcpServers\": {\n \"google-sheets\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-google-sheets@latest\"],\n \"env\": {\n \"GOOGLE_APPLICATION_CREDENTIALS\": \"\u002Fpath\u002Fto\u002Fservice-account.json\"\n }\n }\n }\n}\n```\n\n**选项 2：使用 gcloud auth（无需环境变量）**\n```json\n{\n \"mcpServers\": {\n \"google-sheets\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-google-sheets@latest\"],\n \"env\": {}\n }\n }\n}\n```\n*先决条件：*\n1. *首先运行 `gcloud auth application-default login --scopes=https:\u002F\u002Fwww.googleapis.com\u002Fauth\u002Fcloud-platform,https:\u002F\u002Fwww.googleapis.com\u002Fauth\u002Fspreadsheets,https:\u002F\u002Fwww.googleapis.com\u002Fauth\u002Fdrive`。*\n2. *设置配额项目：`gcloud auth application-default set-quota-project \u003Cproject_id>`*\n\n**🍎 macOS 注意：** 如果出现 `spawn uvx ENOENT` 错误，请将 `\"command\": \"uvx\"` 替换为 `\"command\": \"\u002FUsers\u002Fyourusername\u002F.local\u002Fbin\u002Fuvx\"`（将 `yourusername` 替换为你的实际用户名）。\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>🟡 配置：开发模式（从克隆的仓库运行）\u003C\u002Fsummary>\n\n```json\n{\n \"mcpServers\": {\n \"mcp-google-sheets-local\": {\n \"command\": \"uv\",\n \"args\": [\n \"run\",\n \"--directory\",\n \"\u002Fpath\u002Fto\u002Fyour\u002Fmcp-google-sheets\",\n \"mcp-google-sheets\"\n ],\n \"env\": {\n \"SERVICE_ACCOUNT_PATH\": \"\u002Fpath\u002Fto\u002Fyour\u002Fmcp-google-sheets\u002Fservice_account.json\",\n \"DRIVE_FOLDER_ID\": \"your_drive_folder_id_here\"\n }\n }\n }\n}\n```\n*注意：使用 `--directory` 标志指定项目路径，并调整路径以匹配你实际的工作区位置。*\n\u003C\u002Fdetails>\n\n---\n\n## 💬 Claude 示例提示\n\n连接成功后，可以尝试以下提示：\n\n* “列出我有权访问的所有电子表格。”（或“在我管理的 AI 电子表格文件夹中”）\n* “创建一个名为‘2024 年第三季度销售报告’的新电子表格。”\n* “在‘季度销售报告’电子表格中，获取 Sheet1 范围 A1 到 E10 的数据。”\n* “在 ID 为 `1aBcDeFgHiJkLmNoPqRsTuVwXyZ` 的电子表格中添加一个名为‘Summary’的新工作表。”\n* “在我的‘项目任务’电子表格的‘Tasks’工作表中，将 B2 单元格更新为‘进行中’。”\n* “将以下行追加到电子表格 `XYZ` 的‘Log’工作表中：`[['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']]`”\n* “获取‘销售数据’和‘库存盘点’电子表格的摘要。”\n* “将‘团队假期安排’电子表格以只读权限共享给 `team@example.com`，以写入权限共享给 `manager@example.com`。不要发送通知。”\n* “在我的‘销售报告’电子表格中，根据 A1:B13 范围的数据，创建一个显示每月收入的柱状图。”\n* “在‘市场分析’工作表中添加一个饼图，数据来自 A1:B5，标题为‘按产品划分的市场份额’。”\n* “在电子表格 `abc123` 中，于 Sheet1 上基于 A1:C10 范围创建一个折线图，标题为‘增长趋势’，并标注‘月份’和‘收入’。”\n\n---\n\n## 🆔 ID 参考指南\n\n请使用以下参考指南查找文档中提到的各种 ID：\n\n```\nGoogle Cloud 项目 ID：\n https:\u002F\u002Fconsole.cloud.google.com\u002Fapis\u002Fdashboard?project=sheets-mcp-server-123456\n └───── 项目 ID ─────┘\n\nGoogle Drive 文件夹 ID：\n https:\u002F\u002Fdrive.google.com\u002Fdrive\u002Fu\u002F0\u002Ffolders\u002F1xcRQCU9xrNVBPTeNzHqx4hrG7yR91WIa\n └────────── 文件夹 ID ──────────┘\n\nGoogle Sheets 电子表格 ID：\n https:\u002F\u002Fdocs.google.com\u002Fspreadsheets\u002Fd\u002F25_-_raTaKjaVxu9nJzA7-FCrNhnkd3cXC54BPAOXemI\u002Fedit\n └───────────── 电子表格 ID ─────────────┘\n```\n\n---\n\n## 🤝 贡献\n\n欢迎贡献！请提交问题以讨论错误或功能请求。也欢迎提交拉取请求。\n\n---\n\n## 📄 许可证\n\n本项目采用 MIT 许可证授权 - 详情请参阅 [LICENSE](LICENSE) 文件。\n\n---\n\n## 🙏 致谢\n\n* 基于 [FastMCP](https:\u002F\u002Fgithub.com\u002Fcognitiveapis\u002Ffastmcp) 构建。\n* 灵感来源于 [kazz187\u002Fmcp-google-spreadsheet](https:\u002F\u002Fgithub.com\u002Fkazz187\u002Fmcp-google-spreadsheet)。\n* 使用 Google API Python 客户端库。","# mcp-google-sheets 快速上手指南\n\n`mcp-google-sheets` 是一个基于 Python 的 MCP 服务器，作为 AI 助手（如 Claude Desktop）与 Google Sheets API 之间的桥梁。它允许你通过自然语言指令操作 Google 表格，实现强大的自动化和数据管理工作流。\n\n## 环境准备\n\n在开始之前，请确保满足以下要求：\n\n1. **操作系统**：支持 macOS、Linux 或 Windows。\n2. **Google Cloud 账号**：你需要拥有一个 Google Cloud Platform (GCP) 项目。\n3. **前置依赖**：\n * **启用 API**：在 GCP 控制台中启用 **Google Sheets API** 和 **Google Drive API**。\n * **服务账号 (Service Account)**：创建一个服务账号，下载其 JSON 密钥文件（推荐方式），并将该服务账号添加到你需要访问的 Google Drive 文件夹中（赋予“编辑者”权限）。\n * **获取 ID**：准备好目标 Drive 文件夹的 ID（从文件夹 URL 中获取）。\n\n## 安装步骤\n\n本项目推荐使用 `uv` (一个极速的 Python 包管理器) 运行，无需手动创建虚拟环境或安装依赖。\n\n### 1. 安装 uv\n\n**macOS \u002F Linux:**\n```bash\ncurl -LsSf https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.sh | sh\n```\n\n**Windows (PowerShell):**\n```powershell\npowershell -c \"irm https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.ps1 | iex\"\n```\n\n*安装完成后，请根据终端提示将 `uv` 添加到系统 PATH 环境变量中。*\n\n### 2. 配置环境变量\n\n设置认证所需的凭证路径和 Drive 文件夹 ID。\n\n**macOS \u002F Linux (Bash\u002FZsh):**\n```bash\nexport SERVICE_ACCOUNT_PATH=\"\u002F绝对路径\u002F到你的\u002Fservice-account-key.json\"\nexport DRIVE_FOLDER_ID=\"你的_DRIVE_文件夹_ID\"\n```\n\n**Windows (CMD):**\n```cmd\nset SERVICE_ACCOUNT_PATH=\"C:\\绝对路径\\到你的\\service-account-key.json\"\nset DRIVE_FOLDER_ID=\"你的_DRIVE_文件夹_ID\"\n```\n\n**Windows (PowerShell):**\n```powershell\n$env:SERVICE_ACCOUNT_PATH = \"C:\\绝对路径\\到你的\\service-account-key.json\"\n$env:DRIVE_FOLDER_ID = \"你的_DRIVE_文件夹_ID\"\n```\n\n> **注意**：请将路径替换为你实际的 JSON 密钥文件路径，将 ID 替换为你的 Google Drive 文件夹 ID。\n\n## 基本使用\n\n### 1. 启动服务器\n\n使用 `uvx` 直接运行最新版本的服务器。该命令会自动下载并执行代码。\n\n```bash\nuvx mcp-google-sheets@latest\n```\n\n*建议始终添加 `@latest` 以确保获取最新功能和修复。*\n\n启动成功后，终端将显示日志表明服务器已就绪。\n\n### 2. 连接 MCP 客户端\n\n配置你的 MCP 客户端（例如 Claude Desktop）以连接此服务器。以下是一个典型的 `claude_desktop_config.json` 配置示例：\n\n```json\n{\n \"mcpServers\": {\n \"google-sheets\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-google-sheets@latest\"],\n \"env\": {\n \"SERVICE_ACCOUNT_PATH\": \"\u002F绝对路径\u002F到你的\u002Fservice-account-key.json\",\n \"DRIVE_FOLDER_ID\": \"你的_DRIVE_文件夹_ID\"\n }\n }\n }\n}\n```\n\n重启客户端后，即可在对话中使用自然语言操作表格，例如：\n* “列出我驱动文件夹里的所有表格”\n* “在 'Sales' 表格的 'Sheet1' 中 A1 到 C3 区域写入数据 [[1, 2, 3], [4, 5, 6]]\"\n* “读取 'Report' 表格中的所有数据”\n\n### 3. 优化：按需加载工具 (可选)\n\n默认情况下服务器会加载所有 19 个工具（消耗约 13k tokens）。若只需常用功能，可通过 `--include-tools` 参数或 `ENABLED_TOOLS` 环境变量仅启用特定工具，以节省上下文窗口。\n\n**示例：仅启用读取、写入和列表功能**\n\n```json\n{\n \"mcpServers\": {\n \"google-sheets\": {\n \"command\": \"uvx\",\n \"args\": [\n \"mcp-google-sheets@latest\",\n \"--include-tools\",\n \"get_sheet_data,update_cells,list_spreadsheets,list_sheets\"\n ],\n \"env\": {\n \"SERVICE_ACCOUNT_PATH\": \"\u002F绝对路径\u002F到你的\u002Fservice-account-key.json\",\n \"DRIVE_FOLDER_ID\": \"你的_DRIVE_文件夹_ID\"\n }\n }\n }\n}\n```\n\n可用工具名包括：`get_sheet_data`, `update_cells`, `list_spreadsheets`, `list_sheets`, `create_spreadsheet`, `batch_update_cells` 等。","某电商运营团队需要每日从多个渠道汇总销售数据，并自动生成包含图表和公式的日报表格供管理层审阅。\n\n### 没有 mcp-google-sheets 时\n- 运营人员需手动登录 Google Sheets，逐个复制粘贴来自 CSV 或数据库的原始数据，耗时且极易出错。\n- 每次更新数据后，必须人工重新拖拽填充公式、调整透视表范围，无法实现动态联动。\n- 若需批量创建分地区的日报文件，只能重复机械操作或编写复杂的本地 Python 脚本并处理繁琐的 OAuth 认证。\n- AI 助手虽能分析数据，但因无法直接读写云端表格，只能输出文本建议，无法直接落地为可编辑的电子表格。\n\n### 使用 mcp-google-sheets 后\n- 团队成员只需向 AI 助手发送指令，mcp-google-sheets 即可自动连接 Google Drive，将多源数据清洗后写入指定工作表。\n- 工具支持直接调用 API 插入公式和图表，数据变动时表格内容实时自动更新，彻底解放双手。\n- 通过自然语言即可让 AI 批量创建并按命名规则整理数十个地区日报，底层自动完成服务账号鉴权与文件夹管理。\n- AI 助手结合 mcp-google-sheets 的能力，不仅能分析趋势，还能直接生成并分享带有完整计算逻辑的最终报表文件。\n\nmcp-google-sheets 打通了 AI 思维与云端数据执行的最后一公里，让电子表格自动化从“人工辅助”跃升为“智能原生”。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fxing5_mcp-google-sheets_b256617c.png","xing5","Xing Wu","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fxing5_51b83df6.png",null,"Montreal, CA","xingwu.cs@gmail.com","http:\u002F\u002Fxingwu.me","https:\u002F\u002Fgithub.com\u002Fxing5",[85,89],{"name":86,"color":87,"percentage":88},"Python","#3572A5",98.4,{"name":90,"color":91,"percentage":92},"Dockerfile","#384d54",1.6,786,187,"2026-04-03T09:54:28","MIT","Linux, macOS, Windows","未说明",{"notes":100,"python":101,"dependencies":102},"该工具为基于 Python 的 MCP 服务器，用于连接 Google Sheets API。运行前必须配置 Google Cloud Platform 凭证（推荐使用服务账号），并设置 SERVICE_ACCOUNT_PATH 和 DRIVE_FOLDER_ID 环境变量。可通过 uvx 命令直接运行无需手动安装依赖，支持通过命令行参数或环境变量过滤工具以节省上下文令牌。","未说明 (需安装 uv 包管理器)",[103,67],"uv",[15,45],[106,107,108,109],"google","mcp","mcp-server","spreadsheet","2026-03-27T02:49:30.150509","2026-04-06T07:11:56.622810",[113,118,123,128,133,138],{"id":114,"question_zh":115,"answer_zh":116,"source_url":117},14462,"遇到 'Invalid schema for function' 或读取数据功能失效的错误怎么办？","这通常与客户端提示词（prompt）或所使用的模型有关，而非服务器端代码问题。如果在使用 gpt-4o 等模型时遇到此类架构错误，请尝试优化您的提示词，明确告知模型如何调用工具。维护者指出服务器端无法直接修复此类由模型行为导致的问题。","https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fissues\u002F16",{"id":119,"question_zh":120,"answer_zh":121,"source_url":122},14463,"使用服务账号创建新电子表格时出现 'Permission Denied (403)' 错误如何解决？","这是因为服务账号没有自己的 Google Drive 根目录，直接调用 create() 会尝试写入根目录从而被拒绝。解决方案是改用 drive.files().create() 方法，并显式指定父文件夹 ID（即您的 DRIVE_FOLDER_ID），将文件创建在指定的共享文件夹中，而不是根目录。","https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fissues\u002F24",{"id":124,"question_zh":125,"answer_zh":126,"source_url":127},14464,"为什么读取到的数据行号偏移（总是看到上一行的数据）或难以定位最后一行？","这是旧版本的数据结构问题，MCP 服务器返回的是扁平化数组而非二维数组，导致行索引混乱。请将服务器更新至最新版本以解决此问题，运行命令：`uvx mcp-google-sheets@latest`。v0.4.0 及以上版本已修复数据结构，返回正确的二维数组格式。","https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fissues\u002F7",{"id":129,"question_zh":130,"answer_zh":131,"source_url":132},14465,"get_sheet_data 工具返回的数据是原始列表格式，能否返回结构化的 JSON 对象？","为了保持工具的通用性和低耦合，MCP 工具默认返回最原始的二维数组值，不强制假设第一行是表头。如果您需要结构化数据（如键值对），建议在客户端提示词中处理，例如提示模型：“读取表格数据并将第一行作为键名转换为对象列表”。这样可以兼容没有表头或稀疏数据的表格场景。","https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fissues\u002F8",{"id":134,"question_zh":135,"answer_zh":136,"source_url":137},14466,"运行服务器时出现 'file_cache is only supported with oauth2client\u003C4.0.0' 警告且健康检查失败怎么办？","该警告通常不影响核心功能，但如果导致服务不可用，请确保您使用的是最新版本的包。尝试通过 `uvx mcp-google-sheets@latest` 重新运行以获取最新的依赖修复。同时检查您的服务账号 JSON 密钥文件路径是否正确，以及是否有权限访问指定的 Drive 文件夹。","https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fissues\u002F6",{"id":139,"question_zh":140,"answer_zh":141,"source_url":127},14467,"如何在 Claude 或其他 LLM 中正确配置和使用此 MCP 服务器？","确保在 MCP 配置中正确指定命令和参数。如果使用 uvx，配置示例如下：\n\"gsheet\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-google-sheets@latest\"]\n}\n同时，需要在环境变量中设置 SERVICE_ACCOUNT_PATH 和 DRIVE_FOLDER_ID。如果遇到模型无法正确识别数据范围的问题，请在提示词中明确要求模型先获取元数据或使用具体的 A1 表示法范围（如 'A1:C10'）。",[143,148,153,158,163,168,173,178,183,188],{"id":144,"version":145,"summary_zh":146,"released_at":147},81375,"v0.6.1","## 变更内容\n* 功能：新增 `search_spreadsheets` 和 `find_in_spreadsheet` 工具，由 @dmitry-simple-it 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F60 中实现。\n* 功能：添加工具注解，以提升大模型对工具的理解能力，由 @bryankthompson 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F57 中实现。\n* 增加工具过滤功能，以减少上下文窗口的消耗，由 @Copilot 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F61 中实现。\n* 为 Google Sheets MCP 服务器添加图表创建功能，由 @Copilot 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F62 中实现。\n\n## 新贡献者\n* @dmitry-simple-it 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F60 中完成了首次贡献。\n* @bryankthompson 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F57 中完成了首次贡献。\n* @Copilot 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F61 中完成了首次贡献。\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fcompare\u002Fv0.6.0...v0.6.1","2026-03-15T22:14:01",{"id":149,"version":150,"summary_zh":151,"released_at":152},81376,"v0.6.0","## 变更内容\n* 修复令牌刷新错误处理，防止服务器崩溃，由 @slhck 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F52 中完成\n* 更新 README，使其与实际工具一致，并提升清晰度和详细程度，由 @squatto 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F55 中完成\n* 添加 batch_update 工具，以暴露完整的 batchUpdate 端点（允许 Claude 格式化单元格），由 @drPod 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F54 中完成\n* 杂项：添加回退版本，以应对我没有标签的情况，由 @jhutar 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F47 中完成\n\n## 新贡献者\n* @slhck 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F52 中完成了首次贡献\n* @squatto 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F55 中完成了首次贡献\n* @drPod 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F54 中完成了首次贡献\n* @jhutar 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F47 中完成了首次贡献\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fcompare\u002Fv0.5.2...v0.6.0","2025-12-06T18:44:52",{"id":154,"version":155,"summary_zh":156,"released_at":157},81377,"v0.5.2","## 变更内容\n* 功能新增：添加 Docker 支持，并更新服务器配置，由 @omarsaad98 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F50 中实现。\n* 新增 list_folders 工具，并支持通过指定文件夹 ID 来创建或列出电子表格，由 @lukmanr 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F48 中实现。\n\n## 新贡献者\n* @omarsaad98 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F50 中完成了首次贡献。\n* @lukmanr 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F48 中完成了首次贡献。\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fcompare\u002Fv0.5.1...v0.5.2","2025-11-09T02:48:52",{"id":159,"version":160,"summary_zh":161,"released_at":162},81378,"v0.5.1","## 变更内容\n* 修复 #36：当 `include_grid_data=False`（默认值）时，`get_sheet_data` 返回空值，由 @mcandries 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F37 中完成。\n\n## 新贡献者\n* @mcandries 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F37 中完成了首次贡献。\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fcompare\u002Fv0.5.0...v0.5.1","2025-08-26T18:28:14",{"id":164,"version":165,"summary_zh":166,"released_at":167},81379,"v0.5.0","## 变更内容\n* docs: 由 @domdomegg 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F30 中修复了 ADC 认证的设置说明。\n* feat: 添加 `include_grid_data` 参数到 `get_sheet_data` 函数，并更新文档，由 @iqdoctor 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F33 中完成。\n* 支持共享云端硬盘，并修复了通过服务账号创建电子表格的问题，由 @ykun9 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F28 中完成。\n\n## 新贡献者\n* @domdomegg 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F30 中完成了首次贡献。\n* @iqdoctor 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F33 中完成了首次贡献。\n* @ykun9 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F28 中完成了首次贡献。\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fcompare\u002Fv0.4.1...v0.5.0","2025-08-21T23:29:34",{"id":169,"version":170,"summary_zh":171,"released_at":172},81380,"v0.4.1","## 变更内容\n* 更新 server.py：由 @hupili 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F21 中修复了模型的描述。\n\n## 新贡献者\n* @hupili 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F21 中完成了首次贡献。\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fcompare\u002Fv0.4.0...v0.4.1","2025-07-18T00:56:14",{"id":174,"version":175,"summary_zh":176,"released_at":177},81381,"v0.4.0","## 变更内容\n* 修复：@xing5 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F14 中改进了位置处理\n\n## 新贡献者\n* @xing5 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F14 中完成了首次贡献\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fcompare\u002Fv0.3.6...v0.4.0","2025-05-28T06:16:30",{"id":179,"version":180,"summary_zh":181,"released_at":182},81382,"v0.3.6","## 变更内容\n* 功能：通过 @nutritionengineering 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F12 中实现了按工作表获取公式的功能\n\n## 新贡献者\n* @nutritionengineering 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F12 中完成了首次贡献\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fcompare\u002Fv0.3.5...v0.3.6","2025-05-23T17:21:31",{"id":184,"version":185,"summary_zh":186,"released_at":187},81383,"v0.3.5","**完整更新日志**: https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fcompare\u002Fv0.3.4...v0.3.5","2025-04-22T17:00:32",{"id":189,"version":190,"summary_zh":191,"released_at":192},81384,"v0.3.4","**(已弃用)**：如果您正在使用 v0.3.4 版本，请升级到最新版本，因为存在一个仅允许设置凭据信息的 bug。最简单的方法是使用 `uvx mcp-google-sheets@latest`。\n\n## 变更内容\n* @theboringhumane 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F1 中新增了 get_multiple_sheet_data、get_multiple_spreadsheet_summary 和 share_spreadsheet 工具。\n\n## 新贡献者\n* @theboringhumane 在 https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fpull\u002F1 中完成了首次贡献。\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fxing5\u002Fmcp-google-sheets\u002Fcompare\u002Fv0.2.0...v0.3.4","2025-04-21T23:48:52"]