GSC MCP Server Setup: Complete Troubleshooting Guide for Claude Desktop

Setting up an MCP (Model Context Protocol) server should be straightforward—but in practice, it rarely is. From Node.js version conflicts to macOS path quirks, there are dozens of ways the setup can fail silently.

This guide covers the most common MCP server errors with verified solutions, based on official documentation, community troubleshooting guides, and our own experience building the Ekamoira GSC MCP server.

Quick Diagnosis: Is Your Server Actually Running?

Before diving into specific errors, check if your MCP server is connecting at all:

1. Open Claude Desktop Settings → Developer → Enable Developer Mode

2. Check the MCP logs at ~/Library/Logs/Claude/mcp-server-[name].log

3. Look for the hammer icon in Claude's chat interface—if it's missing, the server isn't loaded

If you see "Connected to MCP server" in logs but tools don't appear, the issue is likely configuration-related. If you see errors, read on.

Error 1: "spawn npx ENOENT"

What it means: Claude Desktop can't find the npx (or node) executable.

Root cause: macOS applications inherit the system $PATH but miss paths added via shell configuration files like .bashrc or .zshrc. (Source: Nish Tahir)

Solution: Use Explicit Paths

Instead of relying on npx, specify the full path to your Node.js binary:

{
  "mcpServers": {
    "my-server": {
      "command": "/Users/yourname/.nvm/versions/node/v22.0.0/bin/node",
      "args": [
        "/Users/yourname/.nvm/versions/node/v22.0.0/lib/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js"
      ]
    }
  }
}

Find your Node path:

which node
# or if using NVM:
nvm which current

Alternative: Create Symlinks

If you prefer using npx, create symlinks in a PATH that Claude Desktop checks:

# macOS with Homebrew
ln -s /opt/homebrew/opt/node@22/bin/npx /opt/homebrew/bin/npx
ln -s /opt/homebrew/opt/node@22/bin/node /opt/homebrew/bin/node

Claude Desktop checks these fixed locations:

• macOS: /opt/homebrew/bin, /usr/local/bin, ~/.nvm/versions/node/*/bin

• Linux: /usr/bin, /usr/local/bin, ~/.nvm/versions/node/*/bin

• Windows: C:\Program Files\nodejs, C:\Program Files\Python3*

Error 2: "parseArgs" Export Error

Full message: SyntaxError: The requested module 'node:util' does not provide an export named 'parseArgs'

Root cause: Your Node.js version is below 18.17. The parseArgs function was added in Node 18.3 and stabilized in 18.17.

Solution: Upgrade Node.js

# Check current version
node --version

# If using NVM, upgrade:
nvm install 18
nvm use 18

# Or install latest:
nvm install node
nvm use node

After upgrading, verify the version and restart Claude Desktop.

Error 3: "args.at is not a function"

Root cause: Mixed Node.js versions or npm compatibility issues. The .at() array method requires Node.js 16.6+.

Solution: Use Explicit Binary Paths

This error often occurs when your shell uses one Node version but Claude Desktop finds another. The fix is the same as Error 1: specify the exact binary path in your configuration.

# Find which Node version has the issue
node -e "console.log([1,2,3].at(-1))"
# Should print: 3
# If it errors, your Node is too old

Error 4: "Cannot find module '[path]/dist/index.js'"

Root cause: The MCP server entry point isn't where you think it is.

Solution: Check the Correct Path

Many MCP servers use a transport file instead of index.js:

# List the actual files
ls -la ./node_modules/@modelcontextprotocol/server-name/dist/

# Check package.json for the bin entry
cat ./node_modules/@modelcontextprotocol/server-name/package.json | grep -A 3 '"bin"'

Often, you need to point to dist/transports/stdio.js instead of dist/index.js.

Error 5: "No module named 'fitz'" (Python Servers)

What it means: A Python MCP server is missing a required dependency.

Root cause: The virtual environment doesn't have all required packages.

Solution: Install Missing Dependencies

# Activate the virtual environment
source .venv/bin/activate

# Install the missing module (fitz is PyMuPDF)
pip install PyMuPDF

# Or reinstall all requirements
pip install -r requirements.txt

Error 6: OAuth Discovery Issues (Claude.ai & ChatGPT)

When using hosted MCP servers with OAuth (like Ekamoira's GSC MCP), you might encounter scope or authorization errors.

Common Issues We've Seen

Fix: Delete and Re-Add the Connection

OAuth clients cache their registration. If scope issues persist:

1. In Claude.ai: Settings → Integrations → Remove the MCP connection

2. Wait 30 seconds for any cached tokens to expire

3. Re-add the connection with the same URL

4. Complete the OAuth flow fresh

The "Silver Bullet" Approach

If you're still struggling after trying the above fixes, here's a comprehensive reset approach (Source: Kaue Cano on Medium):

Step 1: Install NVM for Clean Node Management

# Install NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart terminal, then:
nvm install node
nvm use node

Step 2: Install MCP Servers Globally

npm i -g @modelcontextprotocol/server-filesystem
npm i -g @modelcontextprotocol/server-brave-search
# Add any other servers you need

Step 3: Use Hardcoded Paths Everywhere

{
  "mcpServers": {
    "filesystem": {
      "command": "/Users/yourname/.nvm/versions/node/v23.4.0/bin/node",
      "args": [
        "/Users/yourname/.nvm/versions/node/v23.4.0/lib/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js",
        "/Users/yourname/Documents"
      ]
    }
  }
}

This eliminates all PATH-related issues by specifying exact locations.

Configuration File Location

Claude Desktop reads its MCP configuration from:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

After editing, always restart Claude Desktop to reload the configuration.

Debugging Checklist

Before giving up, run through this checklist:

• Node.js version is 18.17 or higher (node --version)

• Configuration file is valid JSON (use a JSON validator)

• All paths in config are absolute, not relative

• Required API keys are set in env section

• Claude Desktop was restarted after config changes

• Developer Mode is enabled for log access

• MCP logs show no errors (~/Library/Logs/Claude/)

Skip the Hassle: Use a Hosted Solution

If you're setting up a GSC (Google Search Console) MCP server, you can skip all of this complexity.

Ekamoira's hosted GSC MCP handles:

• OAuth authentication (no credential files to manage)

• Server maintenance and updates

• Automatic token refresh

• Works with Claude.ai, ChatGPT, and Cursor

Just enter the URL https://app.ekamoira.com/gsc/mcp and authorize with your Google account. No Node.js, no config files, no troubleshooting.

Try the 30-day free trial →

Summary

Most MCP server issues fall into three categories:

1. Path issues → Use explicit, absolute paths to binaries

2. Version issues → Upgrade Node.js to 18.17+

3. OAuth issues → Delete and re-add the connection

When in doubt, check the MCP logs, verify your Node version, and ensure all paths are absolute. And if you just want GSC data in Claude without the setup headache, consider a hosted solution.

Sources

• Claude Help Center: Getting Started with Local MCP Servers

• MCP Troubleshooting Gist by space-cadet

• Nish Tahir: Notes on Claude Desktop MCP Servers

• Kaue Cano: MCP Services Silver Bullet Approach