自己做一個簡單 Server:不用是工程師

安裝 uv,建立專案資料夾

先確認 uv 已安裝:

uv --version

沒有的話用 Homebrew 安裝(macOS):

brew install uv

Windows 用 winget:

winget install --id=astral-sh.uv -e

建立專案資料夾:

mkdir ~/my-sheets-server
cd ~/my-sheets-server

這個資料夾就是你 server 的家。server.py 放在這裡,之後設定 Claude Desktop 也要用這個路徑。

用 Claude Code 寫 server 程式碼

在 ~/my-sheets-server 資料夾裡打開 Claude Code,直接說:

幫我用 FastMCP 寫一個 MCP server,功能是查詢 Google Sheets。

需求:
1. 使用 gspread 和 google-auth 套件存取 Google Sheets
2. 從環境變數讀取設定:
   - GOOGLE_CREDENTIALS_PATH:服務帳戶 JSON 憑證的完整路徑
   - DEFAULT_SPREADSHEET_ID:預設試算表 ID(可在呼叫工具時覆寫)
3. 提供兩個工具:
   - read_sheet(sheet_name, spreadsheet_id):讀取整張工作表,回傳格式化的純文字表格
   - search_sheet(keyword, sheet_name, spreadsheet_id):搜尋包含關鍵字的列,不分大小寫
4. 兩個工具的 docstring 都要清楚說明:用途、適合的使用情境、參數說明、回傳格式
5. spreadsheet_id 省略時用 DEFAULT_SPREADSHEET_ID 環境變數;sheet_name 預設值「工作表1」
6. 錯誤處理:試算表找不到、無權限、網路錯誤都要回傳繁體中文錯誤訊息
7. 程式碼寫在 server.py

Claude Code 跑完後,你會拿到一份 server.py。以下是它應該長得像的樣子,方便你對照驗收:

import os
from fastmcp import FastMCP
import gspread
from google.oauth2.service_account import Credentials

mcp = FastMCP("Google Sheets 查詢助理")

SCOPES = ["https://www.googleapis.com/auth/spreadsheets.readonly"]


def _get_client():
    """建立 gspread 客戶端,從環境變數取得憑證路徑"""
    credentials_path = os.environ.get("GOOGLE_CREDENTIALS_PATH")
    if not credentials_path:
        raise ValueError("請設定環境變數 GOOGLE_CREDENTIALS_PATH")
    creds = Credentials.from_service_account_file(credentials_path, scopes=SCOPES)
    return gspread.authorize(creds)


def _get_records(spreadsheet_id: str, sheet_name: str) -> list[dict]:
    """取得指定工作表的所有資料列"""
    gc = _get_client()
    sh = gc.open_by_key(spreadsheet_id)
    worksheet = sh.worksheet(sheet_name)
    return worksheet.get_all_records()


def _format_table(records: list[dict]) -> str:
    """把 records 格式化成易讀的純文字表格"""
    if not records:
        return "（工作表是空的）"
    headers = list(records[0].keys())
    separator = "-" * (sum(len(h) for h in headers) + len(headers) * 3)
    rows = [" | ".join(headers), separator]
    for record in records:
        rows.append(" | ".join(str(record.get(h, "")) for h in headers))
    return "\n".join(rows)


@mcp.tool()
def read_sheet(
    sheet_name: str = "工作表1",
    spreadsheet_id: str = "",
) -> str:
    """
    讀取 Google Sheets 工作表的全部資料,回傳格式化的表格文字。
    適合使用情境:「列出所有客戶」、「顯示完整庫存表」、「我的試算表裡有什麼資料」。
    如果使用者問試算表的整體內容,優先使用這個工具。

    Args:
        sheet_name: 工作表分頁的名稱,預設「工作表1」
        spreadsheet_id: 試算表 ID(網址 /d/ 後面那串),省略時使用環境變數預設值
    Returns:
        包含欄位標題與所有資料列的純文字表格,第一行是「共 N 筆資料」
    """
    sid = spreadsheet_id or os.environ.get("DEFAULT_SPREADSHEET_ID", "")
    if not sid:
        return "錯誤:請提供試算表 ID 或設定 DEFAULT_SPREADSHEET_ID 環境變數"
    try:
        records = _get_records(sid, sheet_name)
        return f"共 {len(records)} 筆資料:\n{_format_table(records)}"
    except gspread.exceptions.SpreadsheetNotFound:
        return f"錯誤:找不到試算表 {sid},請確認 ID 是否正確且服務帳戶 email 已加入試算表共用名單"
    except gspread.exceptions.WorksheetNotFound:
        return f"錯誤:找不到工作表「{sheet_name}」,請確認分頁名稱是否正確"
    except Exception as e:
        return f"讀取失敗:{str(e)}"


@mcp.tool()
def search_sheet(
    keyword: str,
    sheet_name: str = "工作表1",
    spreadsheet_id: str = "",
) -> str:
    """
    在 Google Sheets 工作表中搜尋包含關鍵字的資料列,不分大小寫。
    適合使用情境:「找王小明的訂單」、「有沒有蘋果口味的商品」、「搜尋包含 XXX 的紀錄」。
    當使用者要查找特定資料時使用,不需要看全表的情況比 read_sheet 更精準。

    Args:
        keyword: 要搜尋的關鍵字,會比對所有欄位的值
        sheet_name: 工作表分頁的名稱,預設「工作表1」
        spreadsheet_id: 試算表 ID,省略時使用環境變數預設值
    Returns:
        符合條件的資料列表格,或「找不到」的提示訊息
    """
    sid = spreadsheet_id or os.environ.get("DEFAULT_SPREADSHEET_ID", "")
    if not sid:
        return "錯誤:請提供試算表 ID 或設定 DEFAULT_SPREADSHEET_ID 環境變數"
    try:
        records = _get_records(sid, sheet_name)
        matches = [
            r for r in records
            if any(keyword.lower() in str(v).lower() for v in r.values())
        ]
        if not matches:
            return f"在「{sheet_name}」中找不到包含「{keyword}」的資料"
        return f"找到 {len(matches)} 筆相符資料:\n{_format_table(matches)}"
    except Exception as e:
        return f"搜尋失敗:{str(e)}"


if __name__ == "__main__":
    mcp.run()

把 Claude Code 產出的版本和這份對照,確認兩個工具都在、錯誤處理有覆蓋、docstring 有說明使用情境。如果有缺,直接告訴 Claude Code 補上。

取得 Google Sheets API 憑證

這是整個流程裡設定步驟最多的一步,但只需要做一次,以後所有試算表都能用。整體分三個階段,先看全貌再動手:

在 Google Cloud Console 建立服務帳戶

1. 前往 console.cloud.google.com,登入你的 Google 帳號
2. 點左上角「選取專案」→「新增專案」,名字隨意(例如「MCP Tools」)
3. 進入新專案後,左側選單:「API 和服務」→「程式庫」,搜尋 Google Sheets API,點進去按「啟用」
4. 左側選單:「API 和服務」→「憑證」→「建立憑證」→「服務帳戶」
5. 填服務帳戶名稱(例如 mcp-reader),按「建立並繼續」→「繼續」→「完成」
6. 回到憑證頁,點剛建立的服務帳戶 email,進入「金鑰」分頁
7. 「新增金鑰」→「建立新金鑰」→選「JSON」→「建立」,瀏覽器自動下載一個 JSON 憑證檔

把下載的 JSON 移到安全位置,例如:

mkdir -p ~/.secrets
mv ~/Downloads/xxx-xxxx.json ~/.secrets/google-service-account.json

把服務帳戶加進試算表的共用名單

打開下載的 JSON,找到 client_email 欄位,值長得像:

mcp-reader@my-project-123456.iam.gserviceaccount.com

複製這個 email。打開你的 Google Sheets 試算表,點右上角「共用」按鈕,把這個 email 貼進去,權限選「檢視者」即可。按「傳送」。

這一步不做,server 連過去會看到「找不到試算表」的錯誤——即使試算表 ID 完全正確也一樣,因為服務帳戶沒有被授權。

取得試算表 ID

打開你的試算表,看網址列:

https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms/edit

/d/ 和 /edit 之間那一長串就是 spreadsheet ID:

1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms

把這個值記好,等一下設定 Claude Desktop 時要用。

本地測試:用 MCP Inspector 先確認工具能跑

在終端機切到 ~/my-sheets-server,設好環境變數後啟動 dev 模式:

cd ~/my-sheets-server

export GOOGLE_CREDENTIALS_PATH=~/.secrets/google-service-account.json
export DEFAULT_SPREADSHEET_ID=你的試算表ID

uv run --with fastmcp --with gspread --with "google-auth" fastmcp dev server.py

第一次跑這行,uv 會下載所需套件(可能要等三十秒以上,網速慢的話更久——正常現象,不是當掉了)。下載完成後,命令列會顯示:

MCP Inspector is up and running at http://localhost:6274

瀏覽器打開 http://localhost:6274(第一次會自動帶上一組認證 token,直接用終端機印出的完整網址開啟最保險),你會看到 FastMCP 內建的 MCP Inspector 介面:左側列出你的工具名稱,點進去可以填參數、按「Run Tool」執行,右側顯示回傳結果。

在 Inspector 裡測試兩件事:

1. 呼叫 read_sheet(不填 spreadsheet_id,用環境變數預設值)——看能不能拿到試算表資料
2. 呼叫 search_sheet,keyword 填你知道存在的一個關鍵字——確認搜尋有正確回傳

兩個工具都測過、結果正確,再進下一步。在 Inspector 裡排錯比在 Claude Desktop 裡直覺多了,出了問題也更容易看到錯誤訊息。測試完按 Ctrl+C 關掉。

掛進 Claude Desktop,正式上線

打開 Claude Desktop 設定檔(Settings → Developer → Edit Config),在 mcpServers 裡新增你的 server:

{
  "mcpServers": {
    "my-sheets": {
      "command": "uv",
      "args": [
        "run",
        "--with", "fastmcp",
        "--with", "gspread",
        "--with", "google-auth",
        "fastmcp",
        "run",
        "/Users/你的使用者名稱/my-sheets-server/server.py"
      ],
      "env": {
        "GOOGLE_CREDENTIALS_PATH": "/Users/你的使用者名稱/.secrets/google-service-account.json",
        "DEFAULT_SPREADSHEET_ID": "你的試算表ID"
      }
    }
  }
}

三個地方要換成你自己的值:

• server.py 的完整絕對路徑(不能用 ~,要展開成 /Users/yourname/...)
• 憑證 JSON 的完整絕對路徑
• 你的試算表 ID

存檔後完全關掉 Claude Desktop(macOS 按 Cmd+Q),重新打開。成功的話,對話框左下角的錘子 icon 展開,應該能看到 read_sheet 和 search_sheet 兩個工具出現在清單裡。

真實查詢:看著 AI 用你做的工具

開一個新對話,先試一般查詢:

我的試算表裡有什麼資料?幫我列出來。

Claude 應該呼叫 read_sheet 工具,把你的試算表資料整理後回答你。接著試搜尋:

試算表裡有沒有叫王小明的資料?

你會看到 Claude 的回應流程:判斷這是關鍵字查詢 → 呼叫 search_sheet("王小明") → 取得結果 → 用自然語言告訴你找到幾筆、內容是什麼。

這就是「讓 AI 幫 AI 做工具」的完整閉環:Claude Code 幫你寫工具 → 你把工具裝進 Claude Desktop → Claude 靠這個工具幫你查自己的資料。整個過程你沒有打過一行 Python。