Claude MCP Setup: Config Files, Servers, and Troubleshooting

TL;DR: Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/), add your servers, restart Claude. Start with Filesystem or Context7. 90% of issues are JSON syntax errors or forgetting to restart.

Want Claude to access your files, GitHub repos, or databases? Here's the complete setup guide.

30-second version: Create a config file, add your servers, restart Claude. Done.

Quick Start#

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

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

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

Restart Claude Desktop. Ask: "Show me the latest TanStack Router documentation"

That's it. Claude now gets up-to-date library docs.

Config File Locations#

Open the folder:

• macOS: open ~/Library/Application\ Support/Claude/
• Windows: Press Win+R, type %APPDATA%\Claude

Essential Servers#

Start with these — they cover 90% of use cases:

Full Config Example#

Here's a production-ready setup with multiple servers:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_your_token" }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

After restart, Claude gets current library docs, manages GitHub, and automates browsers.

Claude Desktop vs Claude Code#

Claude Desktop Setup#

1. Download from claude.com/download
2. Edit config file (see locations above)
3. Restart Claude completely (quit from menu bar)
4. Look for the hammer icon — MCP is ready

Claude Code Setup#

# Add filesystem access
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects

# Add GitHub with token
claude mcp add github -e GITHUB_TOKEN=ghp_xxx -- npx -y @modelcontextprotocol/server-github

# List all servers
claude mcp list

# Remove a server
claude mcp remove filesystem

One command per server. No JSON editing needed.

Getting GitHub Token#

The GitHub server needs a personal access token:

1. Go to github.com/settings/tokens
2. Click "Generate new token (classic)"
3. Give it repo scope
4. Copy the token (starts with ghp_)

Add to your config:

"env": { "GITHUB_TOKEN": "ghp_your_token_here" }

Security tip: Use environment variables instead of hardcoding:

"env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }

Then set in your shell: export GITHUB_TOKEN="ghp_..."

Troubleshooting#

"Server not appearing"#

"Command not found"#

Claude Desktop on macOS sometimes can't find npx. Use absolute path:

{
  "command": "/usr/local/bin/npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
}

Find your npx path: which npx

"Permission denied"#

"Server crashes immediately"#

Test manually in terminal first:

npx -y @modelcontextprotocol/server-filesystem /your/path

If it fails here, the server has an issue — not Claude.

View Logs#

• Claude Desktop (macOS): ~/Library/Logs/Claude/
• Claude Desktop (Windows): %LOCALAPPDATA%\Claude\Logs\
• Claude Code: claude mcp logs servername

Common JSON Mistakes#

Always validate your JSON before saving!

Frequently Asked Questions#

Where is the Claude MCP JSON file?#

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Can I use MCP with claude.ai (web)?#

No. MCP requires Claude Desktop or Claude Code. The web interface doesn't support servers.

What's the easiest server to start with?#

Filesystem. No tokens needed, just a file path. Immediately useful.

How many servers can I add?#

As many as you want. Just keep the JSON valid and restart after changes.

Why isn't my server working?#

90% of issues: JSON syntax error or didn't restart Claude. Check both first.

Your MCP Toolkit#

Related: What is MCP? | Cursor MCP Setup | GitHub MCP Server