MCP Gsheets

🚀 MCP Google Sheets Server

這是一個用於集成 Google Sheets API 的模型上下文協議（MCP）服務器。藉助它，你可以直接從 MCP 客戶端（如 Claude Desktop）讀取、寫入和管理 Google Sheets 文檔。

🚀 快速開始

1. 前提條件

• Node.js v18 或更高版本
• 啟用了 Sheets API 的 Google Cloud 項目
• 帶有 JSON 密鑰文件的服務賬戶

2. 安裝

# 克隆倉庫
git clone https://github.com/freema/mcp-gsheets.git
# 或者使用 SSH
# git clone git@github.com:freema/mcp-gsheets.git
cd mcp-gsheets

# 安裝依賴
npm install

# 構建項目
npm run build

3. Google Cloud 設置

1. 訪問 Google Cloud 控制檯。
2. 創建一個新項目或選擇現有項目。
3. 啟用 Google Sheets API：
   • 導航到“API 和服務”→“庫”。
   • 搜索“Google Sheets API”並點擊“啟用”。
4. 創建服務賬戶：
   • 轉到“API 和服務”→“憑據”。
   • 點擊“創建憑據”→“服務賬戶”。
   • 下載 JSON 密鑰文件。
5. 共享你的電子表格：
   • 打開你的 Google 表格。
   • 點擊“共享”並添加服務賬戶的電子郵件（來自 JSON 文件）。
   • 授予“編輯者”權限。

4. 配置 MCP 客戶端

簡易設置（推薦）

運行交互式設置腳本：

npm run setup

這將：

• 引導你完成配置過程。
• 自動檢測你的 Node.js 安裝（包括 nvm）。
• 找到你的 Claude Desktop 配置文件。
• 創建正確的 JSON 配置。
• 可選地創建一個用於開發的 .env 文件。

手動設置

如果你更喜歡手動配置，請將以下內容添加到你的 Claude Desktop 配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/claude/claude_desktop_config.json

{
    "mcpServers": {
        "mcp-gsheets": {
            "command": "node",
            "args": ["/absolute/path/to/mcp-gsheets/dist/index.js"],
            "env": {
                "GOOGLE_PROJECT_ID": "your-project-id",
                "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
            }
        }
    }
}

添加配置後，重啟 Claude Desktop。

📦 構建與開發

開發命令

# 開啟熱重載的開發模式
npm run dev

# 為生產環境構建
npm run build

# 類型檢查
npm run typecheck

# 清理構建產物
npm run clean

# 運行 MCP 檢查器進行調試
npm run inspector

# 在開發模式下運行 MCP 檢查器
npm run inspector:dev

任務運行器（可選）

如果你安裝了 Task，可以使用以下命令：

# 安裝依賴
task install

# 構建項目
task build

# 在開發模式下運行
task dev

# 運行代碼檢查器
task lint

# 格式化代碼
task fmt

# 運行所有檢查
task check

開發設置

1. 創建用於測試的 .env 文件：

cp .env.example .env
# 使用你的憑證編輯 .env 文件：
# GOOGLE_PROJECT_ID=your-project-id
# GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
# TEST_SPREADSHEET_ID=your-test-spreadsheet-id

2. 在開發模式下運行：

npm run dev  # 開啟自動重載的監視模式

📋 可用工具

讀取數據

• sheets_get_values - 從指定範圍讀取數據
• sheets_batch_get_values - 從多個範圍讀取數據
• sheets_get_metadata - 獲取電子表格信息
• sheets_check_access - 檢查訪問權限

寫入數據

• sheets_update_values - 向指定範圍寫入數據
• sheets_batch_update_values - 向多個範圍寫入數據
• sheets_append_values - 向表格追加行
• sheets_clear_values - 清除單元格內容

表格管理

• sheets_insert_sheet - 添加新工作表
• sheets_delete_sheet - 刪除工作表
• sheets_duplicate_sheet - 複製工作表
• sheets_copy_to - 複製到另一個電子表格
• sheets_update_sheet_properties - 更新工作表設置

單元格格式設置

• sheets_format_cells - 設置單元格格式（顏色、字體、對齊方式、數字格式）
• sheets_update_borders - 添加或修改單元格邊框
• sheets_merge_cells - 合併單元格
• sheets_unmerge_cells - 取消合併之前合併的單元格
• sheets_add_conditional_formatting - 添加條件格式規則

🔧 代碼質量

代碼檢查

# 運行 ESLint
npm run lint

# 修復可自動修復的問題
npm run lint:fix

代碼格式化

# 使用 Prettier 檢查代碼格式
npm run format:check

# 格式化代碼
npm run format

類型檢查

# 運行 TypeScript 類型檢查
npm run typecheck

❗ 故障排除

常見問題

“身份驗證失敗”

• 驗證 JSON 密鑰路徑是否為絕對路徑且正確。
• 檢查 GOOGLE_PROJECT_ID 是否與你的項目匹配。
• 確保 Sheets API 已啟用。

“權限被拒絕”

• 與服務賬戶電子郵件共享電子表格。
• 服務賬戶需要“編輯者”角色。
• 檢查 JSON 文件中的電子郵件（client_email 字段）。

“未找到電子表格”

• 從 URL 驗證電子表格 ID。
• 格式：https://docs.google.com/spreadsheets/d/[SPREADSHEET_ID]/edit

MCP 連接問題

• 確保你使用的是構建後的版本（dist/index.js）。
• 檢查 Claude Desktop 配置中的 Node.js 路徑是否正確。
• 查看 Claude Desktop 日誌中的錯誤信息。
• 使用 npm run inspector 進行調試。

🔍 查找 ID

電子表格 ID

從 URL 中獲取：

https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit
                                        ↑ 這就是電子表格 ID

工作表 ID

使用 sheets_get_metadata 列出所有工作表及其 ID。

📝 提示

1. 始終使用數據副本進行測試。
2. 使用批量操作以提高性能。
3. 設置適當的權限（只讀 vs 編輯）。
4. 對於大型操作，檢查速率限制。
5. 在操作前使用 sheets_check_access 驗證權限。

🤝 貢獻代碼

1. 分叉倉庫。
2. 創建你的功能分支（git checkout -b feature/amazing-feature）。
3. 運行測試和代碼檢查（npm run check）。
4. 提交你的更改（git commit -m 'Add some amazing feature'）。
5. 推送到該分支（git push origin feature/amazing-feature）。
6. 打開一個拉取請求。

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。