# トラブルシューティング
よくある問題と解決方法です。
## 認証関連
### "No OAuth token found"
**原因**: OAuth認証が完了していない
**解決**:
```bash
cd apps/mcp-server-google
pnpm auth:oauth
```
### "Token has expired"
**原因**: アクセストークンが期限切れで、refresh_tokenもない
**解決**:
```bash
# トークンを削除して再認証
rm .secrets/token.json
pnpm auth:oauth
```
### "Invalid credentials"
**原因**: クレデンシャルファイルが見つからないか、形式が不正
**確認**:
```bash
# ファイルの存在確認
ls -la .secrets/credentials.json
# JSON形式の確認
cat .secrets/credentials.json | jq .
```
### "Access blocked: This app's request is invalid"
**原因**: OAuth同意画面の設定が不完全
**確認**:
1. Google Cloud Console > APIs & Services > OAuth consent screen
2. リダイレクトURIが `http://localhost:3000/oauth/callback` になっているか
3. Test users に自分のメールが追加されているか
### Service Account で "Permission denied"
**原因**: Service Account にファイルが共有されていない
**確認**:
1. Service Account のメールアドレスを確認
2. 対象ファイル/フォルダを Service Account と共有
3. 編集者権限を付与
## API関連
### "The caller does not have permission"
**原因**: APIが有効化されていない、またはスコープ不足
**確認**:
1. Google Cloud Console > APIs & Services > Library
2. 必要なAPI（Gmail, Drive, Sheets, Docs, Calendar）が有効か確認
### Rate Limit (429)
**原因**: Google APIのレート制限に達した
**解決**:
- しばらく待ってから再試行
- リクエスト頻度を下げる
- バッチ処理を検討
### "File not found" (404)
**原因**: ファイルIDが間違っている、またはアクセス権がない
**確認**:
```bash
# ファイルIDの確認（URLから取得）
# https://docs.google.com/spreadsheets/d/ABC123/edit
# → ファイルID: ABC123
```
## 設定関連
### "Folder not in allowlist"
**原因**: `DRIVE_ALLOWLIST_FOLDERS` でフォルダが許可されていない
**解決**:
```bash
# .env に対象フォルダIDを追加
DRIVE_ALLOWLIST_FOLDERS=folder-id-1,folder-id-2,new-folder-id
```
### "Operation not allowed"
**原因**: 機能フラグで無効になっている操作を実行しようとした
**解決**:
```bash
# .env で該当フラグを有効化
GMAIL_MODIFY_LABELS_ENABLED=true
CALENDAR_WRITE_ENABLED=true
```
### 環境変数が読み込まれない
**確認**:
```bash
# 現在の設定を確認
node -e "console.log(require('dotenv').config())"
# .env ファイルの場所確認
pwd
ls -la .env
```
## サーバー関連
### サーバーが起動しない
**確認**:
```bash
# 依存関係の確認
pnpm install
# ビルド確認
pnpm build
# TypeScriptエラーの確認
pnpm typecheck
```
### Claude Code から接続できない
**確認**:
1. `~/.claude/claude_desktop_config.json` の設定
2. パスが正しいか確認
3. サーバーが起動しているか確認
**設定例**:
```json
{
"mcpServers": {
"google": {
"command": "node",
"args": ["/absolute/path/to/company-mcp/apps/mcp-server-google/dist/index.js"]
}
}
}
```
### ログが出力されない
**確認**:
```bash
# ログディレクトリの確認
ls -la logs/
# 権限の確認
mkdir -p logs && chmod 755 logs
# 環境変数の確認
# LOG_TO_FILE=true
# LOG_TO_CONSOLE=true
```
## デバッグ
### ログの確認
```bash
# 今日のログ
cat logs/audit-$(date +%Y-%m-%d).jsonl | jq .
# エラーのみ
cat logs/audit-*.jsonl | jq 'select(.level == "error")'
# 特定ツールのログ
cat logs/audit-*.jsonl | jq 'select(.tool == "gmail_search_messages")'
```
### 詳細ログの有効化
```bash
# .env
LOG_LEVEL=debug
```
### API リクエストの確認
Google Cloud Console > APIs & Services > Metrics でAPIの使用状況を確認できます。
## リセット手順
完全にリセットする場合:
```bash
# 1. トークンを削除
rm -rf .secrets/token.json
# 2. ログをクリア
rm -rf logs/*
# 3. 再認証
pnpm auth:oauth
# 4. サーバー再起動
pnpm dev
```
## サポート
問題が解決しない場合は、以下の情報を含めてIssueを作成してください:
1. エラーメッセージ全文
2. 実行したコマンド
3. `.env` の設定（機密情報はマスク）
4. `logs/` の関連ログ
5. Node.js バージョン (`node -v`)
6. OS 情報
