tastasworld
🤖 AIとつくる

@latest の落とし穴 — mcp SDK 2.0 リリースで mcp-google-sheets がつながらなくなった話

(更新: )約4,100字
uvx mcp-google-sheets@latest の実行が ModuleNotFoundError: No module named 'mcp.server.fastmcp' で失敗する様子 (生成画像)

毎朝、Claude Code にアプリとブログのアクセス集計をしてもらい、Google スプレッドシートに記録しています。その書き込みに使っている MCP サーバが、ある朝つながらなくなっていました。

以前は、MCP が使えないときに Claude Code が勝手に代替手段を考えて、MCP 以外の方法で解決してしまうことがありました。ただ、それだと暫定処理に暫定処理を重ねる悪い癖が出てしまいます。なので「MCP が動いていなかったら、代替手段は取らずに教えて。MCP を修正する方向にして」とお願いしてあります。MCP は再接続が必要になることがまあまああるので、いつも同じ方法で対処したいからです。今回もしっかり再接続を促してくれました。ただ、今回はそれでは直らない、修正が必要なエラーだったようです。

分析・修正・状況説明 (この記事にすること) は Claude Code に任せたので、私の作業は特になく、方針の決定と、実際に動いたかの確認と、この記事の確認だけでした。段取りの補足をひとつだけすると、最初はモニタリング担当のセッションがその場で解決しようとしてくれていたので、課題を別に切り出して、そちらで分析と解決をするようにお願いしました。作業をどう分けるかは、まだこちらから指示しないと難しいようです。

何が問題だったのか、私もよくわかっていませんでした。こうして記事にしてもらうと私も理解できますし、同じ問題で困った方の解決にもつながればと思います。

以降は、分析と修正を担当した Claude Code の執筆です (内容は私が確認・修正しています)。ちなみに記事中のスクリーンショットも Claude Code が撮ったもので、個人情報になりそうな箇所は自分で気づいてぼかしてくれていました。

つながらなくなったのは、Google スプレッドシート用の MCP サーバ (mcp-google-sheets) です。数日前までは問題なく動いていて、設定は何も変わっていません。

モニタリング担当セッションの画面。/mcp からの再接続が -32000 で失敗し、スプレッドシートへの記録待ちデータが溜まっている

モニタリング担当セッションの画面です。/mcp からの再接続が -32000 (Connection closed) で失敗し、スプレッドシートに書き込めないデータが溜まりはじめています。

接続が failed になること自体は初めてではなく、これまでは /mcp からの再接続で数秒で復旧していました。今回が違ったのは、何度再接続しても毎回同じエラーで失敗すること。再接続で直るなら一時的な切断、毎回同じエラーならサーバの起動そのものが失敗している — この切り分けから調査を始めました。

何が起きていたのか

登場するものを先に整理します。

  • mcp-google-sheets — Claude Code から Google スプレッドシートを読み書きする MCP サーバ。xing5 さんが公開されています
  • MCP Python SDK (mcp) — MCP 公式の Python SDK。mcp-google-sheets はこの上に実装されています

この環境では mcp-google-sheets を uvx mcp-google-sheets@latest で起動していました。起動のたびに PyPI 上の最新版を解決する指定です。そして mcp-google-sheets 0.6.3 の依存指定は pyproject.toml にあるとおり mcp>=1.8.0。上限がありません。

そこへ 2026-07-28、mcp SDK の v2.0.0 がリリースされました。メジャーアップデートで、v1 系の mcp.server.fastmcp モジュールは廃止・再編されています (変更点は公式の What’s new in v2 と migration guide にまとまっています)。

依存指定に上限がないので、uvx は素直に mcp 2.0.0 を解決します。一方 mcp-google-sheets 側は server.py 冒頭の import が v1 前提のままなので、起動した瞬間にここで止まります。

File ".../mcp_google_sheets/server.py", line 18, in <module>
    from mcp.server.fastmcp import FastMCP, Context
ModuleNotFoundError: No module named 'mcp.server.fastmcp'

@latest 起動と上限なしの依存指定の組み合わせが、上流のメジャーリリースを2日後にそのまま掴んだ、という構図です。こちらは何も変えていなくても、壊れるときは壊れます。

Claude Code の /mcp 接続管理画面。4つのMCPサーバのうち google-sheets だけが failed と表示されている

障害当日の /mcp 画面です。google-sheets だけが failed になっています。同じ uvx 起動でも、GA4 用の analytics-mcp は依存指定が mcp<2,>=1.24.0 と上限付きなので、この日も普通に動いていました。壊れた側と壊れなかった側の差は、依存指定に <2 があるかどうかだけです。

どう直したか — バージョン固定

起動コマンドを次のように変えました。

変更前:

uvx mcp-google-sheets@latest

変更後:

uvx --with 'mcp<2' mcp-google-sheets==0.6.3

mcp-google-sheets を 0.6.3 に、mcp SDK を v1 系 (解決結果は 1.29.0) に固定しています。これで接続は元に戻りました。

ポイントは、@latest を残して --with 'mcp<2' だけ足すのではなく、本体側も ==0.6.3 に固定したことです。@latest を残すと、将来 mcp-google-sheets が mcp 2 必須 (mcp>=2) に更新されたとき、mcp<2 制約と矛盾して依存解決自体が失敗し、今度は別の理由で起動しなくなります。固定するなら本体と依存をセットで、更新は壊れていないときに意図的に行う運用に切り替えました。

修正後の /mcp 接続管理画面。google-sheets が connected · 20 tools に戻っている

修正後の同じ画面です。google-sheets が connected に戻り、スプレッドシートの読み書きも確認できました。

なお、この固定は当面しのぎでもあります。mcp SDK の v1 系は今後メンテナンスモード (セキュリティ修正のみ) とリリースノートでアナウンスされているので、長期的には mcp-google-sheets 側の v2 対応を待ってピンを更新するのが筋です。作者のリポジトリを確認した時点 (2026-07-30) では、この件の issue / PR はまだ1件もありませんでした。リリースから2日なので、これから増えるのかもしれません (その後、文末の追記のとおり、こちらから報告しました)。

そもそも、なぜ mcp-google-sheets なのか

導入したのは 2026年5月です。当時の選定でも、認証情報を外部の SaaS に渡さずに済む self-host + Service Account 方式を軸に、Drive 連携も一体でドキュメントが充実していた mcp-google-sheets を選んでいます。GitHub のスター数もこの分野では最多で、それは今も変わっていません。

今回の件を機に、選択肢を改めて整理してみました (数値・状況はすべて 2026-07-30 時点)。

サーバ / 方式実装最終更新 / ★今回の mcp SDK 2.0 の影響
xing5/mcp-google-sheets (採用中)Python2026-05-14 / 967★あり — 依存が mcp>=1.8.0 で上限なし
freema/mcp-gsheetsTypeScript2026-07-27 / 87★なし (Python SDK とは別実装)。Service Account 対応
mkummer225/google-sheets-mcpJavaScript2025-04-07 / 137★なし (同上)。ただし更新は1年以上停滞
ringo380/claude-google-sheets-mcpPython2025-09-27 / 18★あり — 同じく mcp>=1.8.0 で上限なし
Composio などのホスト型SaaS—なし (ローカルに依存を持たない)。認証情報を外部サービスに渡す点は要検討
claude.ai の Google Drive コネクタ公式コネクタ—なし。ただし読み取り中心で、セル単位の書き込みはできません

Python 実装の2つは、どちらも上限なしの依存指定なので今回の件の影響を受けます。乗り換えるなら、活発に更新されていて Service Account にも対応した freema/mcp-gsheets が有力に見えます。ただしツール構成が変わるぶん、既存の自動化 (日次記録) の動作検証はやり直しになります。今回は「まずバージョン固定で復旧して、乗り換えは壊れていない平常時に落ち着いて検討する」ことにしました。

今回の学び

  • 毎日使う道具は、動くバージョンで固定して、更新は意図的に。@latest は新しい機能をすぐ試せる半面、上流のリリースで予告なく壊れるリスクと引き換えです
  • 「何も変えていないのに壊れた」ときは、自分の環境より先に直近の上流リリースを疑う。今回は mcp SDK 2.0.0 のリリース2日後の発症で、依存パッケージのリリース履歴を見ればすぐたどり着ける位置に原因がありました
  • 固定は本体と依存をセットで。片方だけの固定は、将来の別の壊れ方につながります
  • 「再接続で直るか」が切り分けの一歩目。直れば一時的な切断、毎回同じエラーなら起動失敗です。後者はサーバを手動起動してエラー出力を見るのが早道でした

同じ ModuleNotFoundError: No module named 'mcp.server.fastmcp' に出会った方の参考になればうれしいです。

追記: 上流に報告しました (2026-07-30)

この記事の公開後、作者のリポジトリにこの件を報告しました → xing5/mcp-google-sheets#86。報告時点で同じ内容の先行報告はなく、初報でした。再現手順・原因 (該当行へのリンク付き)・回避策 (mcp<2)・修正案 (依存の上限追加の diff と、v2 移行で書き換えが必要な3箇所) をまとめてあります。同じ問題に遭遇した方は、上流の対応状況もそちらで追えます。

参考リンク

公式・一次情報

← 記事一覧へ