7. Troubleshooting

1Run the 4 checks

Run these first, in the same place where it fails (Mac terminal or iPhone SSH):

claude -p "say hi"; echo "exit: $?"                 # 1. Claude logged in?
claude mcp list | grep google-sheets                # 2. MCP connected?
ls -la ~/.config/mcp-credentials/                   # 3. Credentials readable?
claude -p --output-format json "how many rows are in my tracker" | python3 -m json.tool   # 4. Full picture

2Find your error below

Installation and OAuth

ModuleNotFoundError: No module named 'mcp.server.fastmcp'

Cause: mcp 2.x renamed FastMCP; mcp-google-sheets expects 1.x. Fix: always run with --with 'mcp<2', including inside claude mcp add.

[Errno 2] No such file or directory: 'credentials.json'

Cause: CREDENTIALS_PATH wasn't set for that command. Common when env vars are typed on separate lines and each runs on its own. Fix: one command with the vars inline, or export them first:

export CREDENTIALS_PATH=$HOME/.config/mcp-credentials/credentials.json
export TOKEN_PATH=$HOME/.config/mcp-credentials/token.json
echo $CREDENTIALS_PATH

DefaultCredentialsError / "All authentication methods failed"

Same cause as above: the server couldn't find the credentials file.

"Safari Can't Open the Page" at localhost:xxxxx

Cause: Safari HTTPS-Only mode blocks the plain-HTTP OAuth callback. Login actually succeeded up to that point. Fix: set Chrome/Firefox as default browser, rm ~/.config/mcp-credentials/token.json, rerun.

"Google hasn't verified this app"

Expected for your own app. Advanced → Go to ... (unsafe) → Allow.

Organization policy blocks project/OAuth creation

School/work admin restriction. Use a personal Gmail and share the sheet with it.

Claude Code

Not logged in · Please run /login

/login is typed inside Claude, not as a shell argument:

claude
/login
/exit

I edited claude_desktop_config.json and nothing changed

That file is for Claude Desktop, a different app. Claude Code uses claude mcp add and ~/.claude/settings.json. If you edited Desktop's file, restore it from your backup.

"Do you trust this folder?" / stuck in a menu

Use ↑ ↓ and Enter (Esc cancels). On iPhone, add arrow keys to the Termius toolbar, or ctrl c and run from ~.

Permission not granted / "approve the permission prompt" in -p mode

-p can't prompt. Add to ~/.claude/settings.json:

"permissions": { "allow": ["mcp__google-sheets"] }

Settings file "lost" my permissions block

Probably not lost: head -30 only shows the top. Check the end:

tail -20 ~/.claude/settings.json
grep -A10 '"permissions"' ~/.claude/settings.json

Only restore a backup if the merge truly broke. Validate with python3 -m json.tool ~/.claude/settings.json.

Answers mention Slack, Notion, Asana... "not connected"

Unused plugin connectors. claude plugin disable productivity, and add "Never mention unconnected connectors" to ~/.claude/CLAUDE.md.

MCP connection

✘ Failed to connect — CONNECTION_CLOSED over SSH, but ✔ Connected on the Mac

Cause: macOS privacy protection (TCC) blocks SSH sessions from ~/Desktop, ~/Documents, ~/Downloads. Tell-tale sign: ls ~/Desktop over SSH says Operation not permitted. Fix: move credentials to ~/.config/mcp-credentials/ and re-register:

mkdir -p ~/.config/mcp-credentials && chmod 700 ~/.config/mcp-credentials
cp ~/Desktop/<old-folder>/*.json ~/.config/mcp-credentials/      # run on the Mac
chmod 600 ~/.config/mcp-credentials/*.json
claude mcp remove google-sheets -s user
claude mcp add google-sheets --scope user \
  --env CREDENTIALS_PATH=$HOME/.config/mcp-credentials/credentials.json \
  --env TOKEN_PATH=$HOME/.config/mcp-credentials/token.json \
  -- $HOME/.local/bin/uvx --with 'mcp<2' mcp-google-sheets

(Granting Full Disk Access to sshd also works, but moving the files is simpler and safer.)

CONNECTION_CLOSED everywhere, right after re-adding

Cause: a stray character in the command. Real example: mcp-google-sheets¬ (Option+L on a Mac keyboard types ¬). Fix: check the confirmation line, reveal hidden characters, re-add:

grep -A6 google-sheets ~/.claude.json | cat -v      # look for M-BM-, or similar

✘ Failed with uvx: command not found (or no clear error)

Claude's environment may not have ~/.local/bin in PATH. Register with the full path $HOME/.local/bin/uvx.

MCP slow to start / times out on first call

uvx cold start can be slow. Add to ~/.zshrc:

export MCP_TIMEOUT=30000

See the real server error

Run the server by hand in the failing environment:

CREDENTIALS_PATH=$HOME/.config/mcp-credentials/credentials.json \
TOKEN_PATH=$HOME/.config/mcp-credentials/token.json \
$HOME/.local/bin/uvx --with 'mcp<2' mcp-google-sheets

Successfully authenticated + waiting = healthy (ctrl c). Anything else is the real error.

Token expired / revoked

rm ~/.config/mcp-credentials/token.json
# rerun the command above and log in again

Shell and commands

zsh: no matches found: ...??

Cause: ? outside quotes is a filename wildcard in zsh. Fix: keep ? inside quotes, or drop it. Optional: setopt no_nomatch in ~/.zshrc.

Claude searches Calendar/Gmail/Drive instead of my sheet

Cause: no sheet context reached Claude. Usually a variable typo ($TS_03_SHEET vs $TS03_SHEET expands to empty), or no ~/.claude/CLAUDE.md. Fix:

echo "[$TS03_SHEET]"          # must not be []
ls ~/.claude/CLAUDE.md

ts03: command not found

source ~/.zshrc
type ts03

Command returns empty output

Run the JSON check (step 4 at the top). If result has text, it's a display issue. If hooks exist in ~/.claude/settings.json (e.g. terminal-specific status scripts), test with them removed; they can misbehave over SSH.

~/.zshrc contains source ~/.zshrc

That line re-sources the file from inside itself. Remove it:

sed -i '' '/^source ~\/\.zshrc$/d' ~/.zshrc

Data

Claude reports an extra category / old item

The sheet may have hidden rows (row numbers skip, e.g. 9 → 11). Claude reads hidden rows. Unhide and delete them, or state in CLAUDE.md which rows to ignore.

Name mismatch warnings ("Advanced AI" vs "Advanced Artificial Intelligence")

Use the sheet's exact spelling in CLAUDE.md, optionally with the short form: Advanced Artificial Intelligence (short: Advanced AI).

Days Left is wrong or not updating

Don't let anything write to that column. Use a formula such as =IFERROR(DATEVALUE(E5)-TODAY(),"") with dates stored as text DD-Mmm-YYYY, and list the column as "never write" in CLAUDE.md.

Pasting multi-line notes splits into many rows

Use | as a separator inside a cell instead of newlines.

Remote access

Operation not permitted on ls ~/Desktop over SSH

macOS privacy protection. Keep working files outside Desktop/Documents, or grant Full Disk Access to sshd (System Settings → Privacy & Security → Full Disk Access).

Works on Wi-Fi, fails on cellular

Expected without a mesh VPN. See Guide 6.

Tailscale can't connect while another VPN is on (iPhone)

iOS allows one VPN at a time. Turn the other off, or use a "Mac mode" Shortcut.

SSH "Connection refused" / timeout

Mac asleep, Remote Login off, or wrong address. Check Sharing settings, Battery sleep settings, and hostname.