Git MCP Server Troubleshooting

🚀 Git MCP サーバートラブルシューティングガイド

このリポジトリは、Git MCP サーバーへの接続問題に関する一般的な解決策を記録しており、実際の運用経験に基づいています。

🚀 クイックスタート

Git MCP サーバーの接続問題が発生している場合は、以下の手順を実行してください。

1. 診断スクリプトを実行して、一般的な問題を特定します。
2. 接続チェックリストに従って、段階的に検証を行います。
3. ログ分析を確認して、エラーパターンを理解します。
4. 特定の問題に対する解決手順を実施します。

✨ 主な機能

1. インストール成功方法

解決策が見つかりました！ 多数のトラブルシューティングの結果、UVX インストーラーがスコープ付きのパッケージ名を正しく処理できないことが判明しました。 完全な解決策と手順については、インストール成功ガイドを参照してください。

2. 一般的な接続問題

パッケージ名の誤り

npm エラー 404 Not Found - GET https://registry.npmjs.org/mcp-server-git - 見つかりませんでした

問題：mcp-server-git を使用しようとしましたが、このパッケージは npm レジストリに存在しません。 解決策：正しいパッケージ名の形式を使用します。

# UVX インストーラーの場合
uvx modelcontextprotocol-git-server

# NPM インストーラーの場合（ある場合）
npm install -g @modelcontextprotocol/git-server

UVX パッケージ名の形式問題

エラー: 有効なパッケージまたは追加名ではありません: "@modelcontextprotocol/git-server"

問題：UVX は @ 記号付きのスコープ付きパッケージ名を受け入れません。 解決策：@ 記号を削除し、ハイフンを使用します。

uvx modelcontextprotocol-git-server

サーバートランスポートの突然のクローズ

Server transport closed unexpectedly, これはプロセスが早期に終了したためかもしれません。

問題：サーバープロセスが初期化前に早期に終了しました。 潜在的な原因：

• 環境変数が正しくない
• ポートの競合
• 依存関係が不足している
• 権限問題
• タグ構成の誤り

認証問題

認証問題は通常、他のタイプのエラーとは異なるエラーを表示します。次のようなメッセージが表示された場合：

Server disconnected. {"context":"connection"}

これは接続問題を示しており、認証問題ではありません。

3. 追加の接続問題

ポートの競合

Claude デスクトップまたは他のアプリケーションが同じポートを使用している場合：

エラー: EADDRINUSE: address already in use :::3000

解決策：

• 設定でポートを変更します。
• 環境変数を使用します：GIT_SERVER_PORT=3001
• 競合するプロセスを確認して閉じます。

環境変数の問題

異なる Git プロバイダーには、異なる環境変数が必要です。

• GitHub: GITHUB_TOKEN
• GitLab: GITLAB_PERSONAL_ACCESS_TOKEN（GITLAB_ACCESS_TOKEN ではない） 誤った名前の環境変数を使用すると、接続に失敗します。

プロセス管理の問題

複数のサーバーインスタンスが相互に干渉する可能性があります。

• 古いロックファイルが新しいサーバーインスタンスの起動を妨げる
• 複数のプロセスが同じログに書き込もうとすると、ログファイルのアクセス競合が発生する
• Claude デスクトップが独自のサーバーインスタンスを起動し、競合が発生する

📚 ドキュメント

💻 使用例

基本的な使用法

接続を修復した後、以下のコマンドで接続を検証します。

# カスタムポートでサーバーを起動する
uvx modelcontextprotocol-git-server --env GIT_SERVER_PORT=3001

# アプリケーションを再起動する
# その後、機能メニューの Git ツールを確認する

以下のログが表示されれば、接続が成功しています。

[git-server] [info] Server started and connected successfully