Troubleshooting

Solutions to common problems when installing or using data.gv.at MCP Server.

macOS: "spawn uvx ENOENT" or "Failed to spawn process"

Symptom: Server works in Terminal but fails in Claude Desktop with these log messages:

Using MCP server command: uvx with args and path: { paths: ['/usr/bin', '/bin', '/usr/sbin', '/sbin'] }
Failed to spawn process: No such file or directory
Server transport closed unexpectedly

Root cause: macOS GUI applications (like Claude Desktop) don't inherit your shell's PATH. They only see the minimal system PATH (/usr/bin:/bin:/usr/sbin:/sbin), which doesn't include where uvx is installed (typically ~/.local/bin or /opt/homebrew/bin).

Automatic fix: The CLI installer (uvx datagvat-mcp init) now automatically uses the absolute path to uvx on macOS. Run uvx datagvat-mcp init or uvx datagvat-mcp update to apply the fix.

Manual fix (if automatic fix doesn't work)

If the automatic fix doesn't resolve the issue, manually update your config:

Step 1: Find your uvx path

which uvx

Example output: /Users/yourname/.local/bin/uvx

Step 2: Edit your Claude Desktop config

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Step 3: Replace "command": "uvx" with the absolute path:

{
  "mcpServers": {
    "datagvat": {
      "command": "/Users/yourname/.local/bin/uvx",
      "args": ["datagvat-mcp"]
    }
  }
}

Step 4: Fully quit Claude Desktop (Cmd+Q, not just close window) and restart.

Verification: The "datagvat" server should now appear with a green indicator.

Server not appearing in Claude Desktop

Symptom: Data.gv.at MCP Server doesn't show in Claude Desktop toolbar after installation

Common causes and fixes:

Fix 1: Check configuration file syntax

Invalid JSON prevents Claude Desktop from loading the configuration.

Validate JSON syntax:

python3 -m json.tool ~/.claude/claude_desktop_config.json

python -m json.tool "%APPDATA%\Claude\claude_desktop_config.json"

Expected output: Formatted JSON (no errors)

If you see errors, check for:

Missing comma between entries
Extra comma after last entry
Unmatched brackets or quotes
Missing quotes around keys or values

Fix 2: Use absolute paths

Relative paths fail in MCP configuration.

Always use absolute paths in MCP configuration. Relative paths and tilde (~) expansion are not supported.

Wrong:

{
  "cwd": "~/datagvat-mcp/mcp",          // Fails: tilde not expanded
  "cwd": "../datagvat-mcp/mcp"         // Fails: relative path
}

Correct:

{
  "cwd": "/Users/yourname/datagvat-mcp/mcp",      // macOS/Linux
  "cwd": "C:\\Users\\YourName\\datagvat-mcp\\mcp"  // Windows
}

Windows users: Remember to escape backslashes (use \\ instead of \)

Fix 3: Restart Claude Desktop properly

Configuration is only loaded on startup. Simple window closing doesn't fully quit the application.

Proper restart:

Press Cmd+Q (not just close window)
Wait 5 seconds
Relaunch from Applications

Verify quit: Claude Desktop should NOT appear in Dock

Proper restart:

killall claude-desktop
# Wait 5 seconds
claude-desktop &

Proper restart:

Right-click system tray icon → Exit
Wait 5 seconds
Relaunch from Start menu

Verify quit: No Claude Desktop process in Task Manager

Verification: After restart, "datagvat" appears in bottom toolbar with green indicator

Tools not working

Symptom: Server connected but tool calls fail or return errors

Fix 1: Check Python version

Data.gv.at MCP Server requires Python 3.11 or higher.

Check version:

python --version

If version is 3.10 or lower:

Download Python 3.11+
Reinstall dependencies after upgrade

Fix 2: Reinstall dependencies

Corrupted or incomplete installation can cause tools to fail.

cd /path/to/datagvat-mcp/mcp
uv pip install -e . --force-reinstall

cd /path/to/datagvat-mcp/mcp
pip install -e . --force-reinstall

Verification:

python -c "from app.server import mcp; print('OK')"

Expected output: OK

Fix 3: Check virtual environment

If using a virtual environment, ensure it's activated before running commands.

Check if activated:

which python  # macOS/Linux
where python  # Windows

Expected: Path should point to your venv directory

If not activated:

source /path/to/datagvat-mcp/mcp/.venv/bin/activate

C:\path\to\datagvat-mcp\mcp\.venv\Scripts\activate

Connection errors when using tools

Symptom: Tools execute but fail with connection errors or timeout messages

Fix 1: Check network access

Data.gv.at MCP Server needs HTTPS access to data.gv.at API.

Test API access:

curl https://www.data.gv.at/api/hub/search/catalogues

Expected output: JSON response with catalogue list

If connection fails:

Check firewall settings (allow HTTPS outbound to data.gv.at)
Check corporate proxy configuration
Try from different network (mobile hotspot)

Fix 2: Verify API endpoint

Ensure you can reach the API from your location.

Test with timeout:

curl -m 10 https://www.data.gv.at/api/hub/search/catalogues

If timeout occurs:

Network routing issue or firewall blocking
Contact network administrator if on corporate network

Import errors

Symptom: ModuleNotFoundError or ImportError when running server

Fix: Verify installation

Ensure all dependencies are installed.

Check installation:

cd /path/to/datagvat-mcp/mcp
pip list | grep -E "fastmcp|httpx|pydantic"

Expected: All three packages should appear

If missing:

pip install -e .

Performance issues

Symptom: Tools run slowly or timeout

Fix: Increase timeout settings

Some operations may take longer on slower connections.

Default timeout is 30 seconds. If you experience frequent timeouts on large datasets, consider upgrading your network connection or requesting smaller previews.

Workaround: Use smaller preview limits

Instead of: "Show first 1000 rows"
Try: "Show first 100 rows"

Still having problems?

Check log files

Claude Desktop logs contain detailed error messages.

Location: ~/Library/Logs/Claude/

tail -f ~/Library/Logs/Claude/mcp*.log

Location: ~/.config/Claude/logs/

tail -f ~/.config/Claude/logs/mcp*.log

Location: %APPDATA%\Claude\logs\

Open in text editor or view in terminal:

type "%APPDATA%\Claude\logs\mcp*.log"

What to look for:

Python error messages and stack traces
Connection errors or timeout messages
Configuration loading errors

Get help

If you're still stuck after trying these solutions:

GitHub Issues: Report a bug
GitHub Discussions: Ask questions

Include in your report:

Operating system and version
Python version (python --version)
Full error message from logs
Steps to reproduce the problem
What you've already tried from this guide

On this page