Google Sheets MCP Server

🚀 Google Sheets MCP 服務器

這是一個專為 Google Sheets 設計的模型上下文協議 (MCP) 服務器，它讓 Claude Desktop 能夠直接與 Google Sheets 進行交互。該服務器提供了一系列工具，可用於創建、讀取、寫入和管理 Google Sheets。

🚀 快速開始

本服務器是為 Google Sheets 量身打造的 MCP 服務器，藉助它，Claude Desktop 能與 Google Sheets 直接交互，提供了創建、讀取、寫入和管理表格的工具。下面為你介紹使用前的安裝、配置及使用方法。

✨ 主要特性

• 創建新的 Google 表格
• 讀取和寫入數據到現有表格
• 格式化單元格和範圍
• 添加和刪除表格
• 寫入公式
• 搜索表格
• 列出可用表格

📦 安裝指南

先決條件

• Python 3.10 或更高版本
• 已啟用 Google Sheets API 的 Google Cloud 項目
• 來自 Google Cloud Console 的 OAuth 2.0 憑證
• Claude Desktop 應用程序
• uv 包管理器（推薦）

安裝步驟

1. 克隆倉庫：

git clone https://github.com/yourusername/google-sheets-mcp-server.git
cd google-sheets-mcp-server

2. 創建並激活虛擬環境：

python -m venv .venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

3. 使用 uv 安裝依賴項：

uv pip install -e .

4. 設置 Google Cloud 憑證：
   • 訪問 Google Cloud Console
   • 創建新項目或選擇現有項目
   • 啟用 Google Sheets API 和 Google Drive API
   • 創建 OAuth 2.0 憑證（桌面應用）
   • 下載憑證並保存為 ~/.config/google_sheets_mcp/google-sheets-mcp.json

📚 詳細文檔

配置

配置 Claude Desktop

• 打開 Claude Desktop 設置
• 在 claude_desktop_config.json 中添加以下內容：

{
  "mcpServers": {
    "google_sheets": {
      "command": "/path/to/your/.venv/bin/python",
      "args": [
        "/path/to/your/google_sheets.py",
        "--credentials-path",
        "/Users/yourusername/.config/google_sheets_mcp/google-sheets-mcp.json",
        "--log-level",
        "DEBUG"
      ]
    }
  }
}

首次設置

• 手動運行服務器以完成 OAuth 身份驗證：

python google_sheets.py --credentials-path ~/.config/google_sheets_mcp/google-sheets-mcp.json

• 根據瀏覽器提示授權應用程序
• 令牌將自動保存以便將來使用

使用方法

設置完成後，您可以在 Claude Desktop 中使用以下命令：

• 創建新表格：create_sheet(title: str)
• 格式化單元格：format_range(file_id: str, range: str, format: dict)
• 寫入公式：write_formula(file_id: str, range: str, formula: str)
• 添加表格：add_sheet(file_id: str, title: str)
• 刪除表格：delete_sheet(file_id: str, sheet_id: int)
• 獲取表格屬性：get_sheet_properties(file_id: str)

開發

項目結構

google-sheets-mcp-server/
├── .venv/                  # 虛擬環境
├── google_sheets.py        # 主服務器實現
├── pyproject.toml         # 項目配置和依賴項
├── tests/                 # 測試文件
└── README.md             # 此文件

添加新功能

1. 將新的工具方法添加到 GoogleSheetsMCP 類中
2. 使用 @mcp.tool() 裝飾器裝飾它們
3. 更新 README 中的新功能文檔

運行測試

pytest

故障排除

服務器連接問題

• 檢查服務器是否在運行
• 驗證憑證路徑是否正確
• 查看 Claude Desktop 的日誌

身份驗證問題

• 確保 OAuth 2.0 憑證有效
• 檢查應用程序是否有正確的權限
• 確認使用的是最新版本的庫和工具

其他問題

• 查看控制檯輸出以獲取詳細錯誤信息
• 確保 Google Sheets API 已正確啟用
• 驗證所有依賴項是否已安裝

💻 使用示例

基礎用法

# 這是一個簡單的示例，展示瞭如何使用 google_sheets.py 庫進行基本操作。

from google_sheets import GoogleSheetsMCP

# 初始化 MCP 服務器
mcp = GoogleSheetsMCP(credentials_path='path/to/google-sheets-mcp.json')

# 創建新表格
sheet_id = mcp.create_sheet('示例表格')

# 寫入數據到表格
mcp.write_formula(sheet_id, 'A1', '=SUM(1,2)')

# 讀取單元格內容
value = mcp.read_cell(sheet_id, 'A1')
print(value)  # 輸出: 3

# 刪除表格
mcp.delete_sheet(sheet_id)

常見問題解答

問：如何處理 OAuth 身份驗證錯誤？ 答：請確保您的 Google Cloud 項目已啟用正確的 API，並且憑證文件路徑正確。檢查控制檯輸出以獲取具體錯誤信息。

問：無法連接到 Google Sheets？ 答：確認互聯網連接正常，Google Sheets API 已啟用，並且使用的憑證具有適當權限。

聯繫方式

如需幫助或報告問題，請訪問 項目主頁 或發送郵件至 support@yourdomain.com。