Troubleshooting

If you encounter issues while setting up or using the VibeMap MCP Server, check the common solutions below.

Connection Issues

Claude Desktop doesn't show the "Hammer" icon

The hammer icon indicates that Claude has successfully loaded at least one MCP server. If it's missing:

1. Check Configuration Path: Ensure your claude_desktop_config.json is in the correct folder:

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

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

2. Validate JSON: Ensure the JSON file is valid. A single missing comma can prevent Claude from loading any servers.

3. Absolute Paths: Claude requires absolute paths for both the node executable and the server script.

   • ❌ node ./build/index.js

   • ✅ /usr/local/bin/node /Users/name/code/vibemap/mcp-server/build/index.js

"Server not found" or "Timeout"

1. Build the Server: Ensure you have run npm run build in the mcp-server directory. The build/index.js file must exist.

2. Node Version: Ensure you are using Node.js v18 or higher.

3. Environment Variables: Double-check that VIBEMAP_API_KEY is provided in the env section of your config.

Authentication Issues

"Unauthorized" Error when running tools

1. API Key Validity: Ensure your Personal Access Token (starting with vm_) is still active in the VibeMap Dashboard.

2. Permissions: Ensure the token was generated by the account that owns the projects you are trying to access.

3. Base URL: If you are using the cloud version of VibeMap, ensure VIBEMAP_BASE_URL is set to https://vibemap.ai.

Tool-Specific Issues

sync_to_vibemap fails or returns empty results

1. Check Path: Ensure the local path you provided exists and is accessible by the user running Claude.

2. Exclusions: The scanner ignores node_modules and .git by default. If your code is only in those folders, nothing will be found.

3. Large Codebases: For very large projects, the analysis might time out. Try syncing specific sub-directories instead.

Viewing Logs

Claude Desktop logs all MCP communication. This is the best way to see the exact error message:

• macOS: tail -f ~/Library/Logs/Claude/mcp.log

• Windows: Check %APPDATA%\Claude\logs\mcp.log

Look for lines starting with [vibemap] or stderr output from the node process.