Installation

Install dependencies and verify the server works

Quick Start

1. Install uv package manager

   uv is a fast Python package manager required to run the Arch MCP Server.

   Prerequisites: Python 3.11+ - Check version: python --version

   Arch Linux

   sudo pacman -S uv
   

   Verify installation: uv --version

   Additional Installation Methods

   Manual Installation

   Download pre-built binaries from the GitHub Releases page:

   1. Download the appropriate binary for your operating system
   2. Extract the binary to a directory in your PATH
   3. Make the binary executable (Linux/macOS): chmod +x uv

   Conda/Mamba

   If you use conda or mamba, you can install uv from conda-forge:

   conda install -c conda-forge uv
   # or
   mamba install -c conda-forge uv
   
2. Install Arch MCP Server

   Choose the appropriate transport method for your use case.

   STDIO Transport (Recommended)

   For standard MCP clients like Claude Desktop, Cursor, and VS Code:

   uvx arch-ops-server
   

   uvx automatically manages dependencies and keeps the server isolated from your system Python.

   HTTP/SSE Transport (Smithery)

   For HTTP-based deployments via Smithery, follow the setup instructions at:

   https://smithery.ai/server/@nihalxkumar/arch-mcp

   Smithery provides one-click setup with automatic configuration for Claude Desktop, Cursor, and other MCP clients.

   Test the server: echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | uvx arch-ops-server

3. Configure your MCP client

   Add the Arch MCP Server to your AI assistant’s configuration:

   Claude Desktop

   Config file location:

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

   Add this configuration:

   claude_desktop_config.json

   {
     "mcpServers": {
       "arch-ops": {
         "command": "uvx",
         "args": ["arch-ops-server"]
       }
     }
   }
   

   Must restart Claude Desktop completely after saving config changes.

   Cursor

   

   Or manually configure:

   Config file location:

   • macOS/Linux: ~/.cursor/mcp.json
   • Windows: %APPDATA%\Cursor\mcp_config.json

   Add this configuration:

   mcp.json

   {
     "mcpServers": {
       "arch-ops": {
         "command": "uvx",
         "args": ["arch-ops-server"]
       }
     }
   }
   

   Restart Cursor after saving config changes.

   VS Code

   Config file location:

   • macOS/Linux: ~/.config/Code/User/mcp_servers.json
   • Windows: %APPDATA%\Code\User\mcp_servers.json

   Add this configuration:

   mcp_servers.json

   {
     "mcpServers": {
       "arch-ops": {
         "command": "uvx",
         "args": ["arch-ops-server"]
       }
     }
   }
   

   Requires the MCP extension to be installed from the VS Code marketplace.

   Cline

   Config file location:

   • macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
   • Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
   • Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

   Add this configuration:

   cline_mcp_settings.json

   {
     "mcpServers": {
       "arch-ops": {
         "command": "uvx",
         "args": ["arch-ops-server"]
       }
     }
   }
   
4. Verify the connection

   After restarting your MCP client, verify that arch-ops appears in the connected MCP servers list.

   Success indicators:

   • arch-ops server appears in MCP servers list
   • Tools are available (try searching the Arch Wiki)
   • No connection errors in client logs

   Try your first query: “Search the Arch Wiki for systemd basics”

Troubleshooting

Server not appearing in MCP client

Symptoms:

• arch-ops doesn’t show in MCP servers list
• No tools available from arch-ops

Solutions:

1. Verify uvx installation:

   which uvx
   uvx --version
   

2. Check config file syntax:

   • Ensure JSON is valid (no trailing commas)
   • Verify file path is correct for your OS

3. Restart client completely:

   • Quit application (not just close window)
   • Relaunch and check logs

4. Test server directly:

   echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | uvx arch-ops-server
   

Check client logs for detailed error messages (see log locations in next accordion).

Where to find logs

Claude Desktop:

• macOS: ~/Library/Logs/Claude/mcp*.log
• Linux: ~/.config/Claude/logs/mcp*.log
• Windows: %APPDATA%\Claude\logs\mcp*.log

Cursor:

• macOS/Linux: ~/.cursor/logs/mcp*.log
• Windows: %APPDATA%\Cursor\logs\mcp*.log

VS Code:

• Open Output panel (View → Output)
• Select “MCP” from the dropdown

View logs in real-time:

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

# Or use your log location

uvx command not found

Cause: uv/uvx not installed or not in PATH

Solution:

1. Install uv (see Step 1 above)

2. Add to PATH:

   # Add to ~/.bashrc or ~/.zshrc
   export PATH="$HOME/.local/bin:$PATH"
   
   # Reload shell
   source ~/.bashrc  # or ~/.zshrc
   

3. Verify:

   which uvx
   uvx --version
   

Permission denied errors

Cause: Insufficient permissions for installation directory

Solutions:

1. Don’t use sudo with uvx - it installs to user directory

2. Check directory permissions:

   ls -la ~/.local/bin
   chmod +x ~/.local/bin/uvx  # if needed
   

3. Reinstall uv:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

Connection timeout errors

Symptoms:

• Tools hang or timeout
• “Request timeout” errors

Common Causes:

• Network connectivity issues
• Arch Wiki or AUR temporarily unavailable
• Firewall blocking requests

Solutions:

1. Test network connectivity:

   curl -I https://wiki.archlinux.org
   curl -I https://aur.archlinux.org
   ping archlinux.org
   

2. Check firewall rules:

   • Ensure MCP server can make outbound HTTPS requests
   • Check corporate proxy settings if applicable

3. Try again later:

   • Services might be temporarily down
   • Check Arch Linux Status

If timeouts persist, check if your network has strict firewall rules blocking the MCP server process.

Python version issues

Error: “Python 3.11+ required”

Solution:

1. Check Python version:

   python --version
   python3 --version
   

2. Install Python 3.11+:

   # Arch Linux
   sudo pacman -S python
   
   # macOS (Homebrew)
   brew install python@3.11
   
   # Ubuntu/Debian
   sudo apt install python3.11
   

3. Verify uv uses correct Python:

   uvx --python python3.11 arch-ops-server
   

Still having issues? Check the Troubleshooting Guide for more detailed solutions.

---

Next Steps

Usage Examples

Try common use cases and queries

Features Overview

Learn about all capabilities