Skip to main content

​
Troubleshooting

​
Verify Installation

After installing and configuring the Arch MCP Server:
1

Client Settings

Go to settings tab and Look for MCP tools icon in your client.
2

Find arch-ops Server

You should see “arch-ops” listed as a connected MCP server
3

Test a Simple Query

Try: Search the Arch Wiki for 'installation guide'

​
Common Installation Issues

  1. Verify uvx is installed: uvx --version
  2. Check Python version: python --version (need 3.11+)
  3. Reinstall: uvx --reinstall arch-ops-server
  4. Restart your MCP client
  1. Check config file has valid JSON (no trailing commas)
  2. Verify file location is correct for your client
  3. Completely quit and restart the client (not just reload)

​
Server Won’t Start

Error: command not found: uvx or permission errorsSolution:
  • Install uv first: pip install uv or use your package manager
  • Verify uvx is available: uvx --version
  • Check if uv is in your PATH: which uv
Error: Python 3.11+ requiredSolution:
python --version  # Check current version
# Install Python 3.11+ through your package manager
sudo pacman -S python  # on Arch
Error: ModuleNotFoundError or package installation failsSolution:
uvx --reinstall arch-ops-server  # Reinstall the package
# or
uvx --upgrade arch-ops-server    # Upgrade to latest version
Error: Server shows in tools but says “disconnected”Solution:
  1. Verify Python is installed: python --version
  2. Test server manually: uvx arch-ops-server
  3. Check uvx installation: uvx --version
  4. Restart your MCP client
  5. Check client logs for specific errors

​
Tools Return Errors

Error: command 'checkupdates' not foundSolution: This is Arch-only and requires pacman-contrib:
sudo pacman -S pacman-contrib
On non-Arch systems, this tool is not available.
Error: TimeoutError or request timed outSolution:
  1. Check internet connection: ping google.com
  2. Try a simpler query first
  3. Verify Arch Wiki and AUR are accessible:
    • Wiki: xh https://wiki.archlinux.org/api.php
    • AUR: xh https://aur.archlinux.org/rpc
  4. Increase timeout if needed (requires code change)
Error: AUR package not found or HTTP 404Solution:
  1. Double-check package name spelling
  2. Try searching instead: Search AUR for 'package-name'
  3. The AUR might be temporarily down (rare)
  4. Try again in a few minutes
Error: Too many requests or HTTP 429Solution:
  • AUR has rate limiting
  • Wait a few minutes before retrying
  • Don’t spam requests
  • Share your use case (it’s reasonable)

​
Platform-Specific Issues

​
On Non-Arch Systems

FeatureStatusWorkaround
Wiki search & reading✅ FullWorks perfectly
AUR search & PKGBUILD✅ FullWorks perfectly
Official package info⚠️ Remote APIUses online API instead of local pacman
Update checking❌ Not availableRequires Arch Linux

​
On Arch Linux

All features available. If something isn’t working:
  1. Check system is updated: sudo pacman -Syu
  2. Verify dependencies: which pacman checkupdates yay paru
  3. Test locally: pacman -Si python (should work)

​
Configuration Issues

Error: JSON parse error or invalid configurationSolution:
  1. Validate JSON: Use jq or an online JSON validator
  2. Check for trailing commas
  3. Ensure proper JSON formatting
  4. Example valid config:
{
  "mcpServers": {
    "arch-ops": {
      "command": "uvx",
      "args": ["arch-ops-server"]
    }
  }
}
Error: MCP server doesn’t appear in clientSolution:
  1. Restart your MCP client completely
  2. Check config file location:
    • Claude: ~/.config/Claude/claude_desktop_config.json
    • Cursor: ~/.cursor/mcp_config.json
  3. Verify file has valid JSON
  4. Clear client cache if available

​
Getting Help

​
Debug Commands

# Test server directly (for debugging)
uvx arch-ops-server

# Check uvx installation
uvx --version

# Reinstall if needed
uvx --reinstall arch-ops-server

# View recent logs
journalctl -xe  # system logs
tail -f ~/.config/Claude/logs  # Claude logs (if available)

​
Resources

  • Arch Wiki Issues: Check Arch Wiki
  • AUR Issues: Check AUR
  • MCP Protocol: Review MCP Docs
  • Bug Reports: Open an issue on GitHub
  • Feature Requests: GitHub discussions
Still stuck? Check the server logs, verify your config is correct, and ensure all prerequisites are installed.