> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nihalxkumar.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install dependencies and verify the server works

## Quick Start

<Steps>
  <Step title="Install uv package manager">
    **uv** is a fast Python package manager required to run the Arch MCP Server.

    <Info>
      **Prerequisites:** Python 3.11+ - Check version: `python --version`
    </Info>

    <CodeGroup>
      ```bash Arch Linux theme={null}
      sudo pacman -S uv
      ```

      ```bash Homebrew (macOS/Linux) theme={null}
      brew install uv
      ```

      ```bash Scoop (Windows) theme={null}
      scoop install uv
      ```

      ```bash pip (Python) theme={null}
      pip install uv
      ```

      ```bash Cargo (Rust) theme={null}
      cargo install uv
      ```

      ```bash Other Linux/macOS theme={null}
      curl -LsSf https://astral.sh/uv/install.sh | sh
      ```

      ```bash Windows theme={null}
      powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
      ```
    </CodeGroup>

    <Check>
      Verify installation: `uv --version`
    </Check>

    <Accordion title="Additional Installation Methods">
      #### Manual Installation

      Download pre-built binaries from the [GitHub Releases page](https://github.com/astral-sh/uv/releases):

      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:

      ```bash theme={null}
      conda install -c conda-forge uv
      # or
      mamba install -c conda-forge uv
      ```
    </Accordion>
  </Step>

  <Step title="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:

    ```bash theme={null}
    uvx arch-ops-server
    ```

    <Tip>
      `uvx` automatically manages dependencies and keeps the server isolated from your system Python.
    </Tip>

    ### HTTP/SSE Transport (Smithery)

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

    **[https://smithery.ai/server/@nihalxkumar/arch-mcp](https://smithery.ai/server/@nihalxkumar/arch-mcp)**

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

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

  <Step title="Configure your MCP client">
    Add the Arch MCP Server to your AI assistant's configuration:

    <Tabs>
      <Tab title="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:**

        ```json claude_desktop_config.json theme={null}
        {
          "mcpServers": {
            "arch-ops": {
              "command": "uvx",
              "args": ["arch-ops-server"]
            }
          }
        }
        ```

        <Warning>
          **Must restart Claude Desktop completely** after saving config changes.
        </Warning>
      </Tab>

      <Tab title="Cursor">
        ![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)

        **Or manually configure:**

        **Config file location:**

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

        **Add this configuration:**

        ```json mcp.json theme={null}
        {
          "mcpServers": {
            "arch-ops": {
              "command": "uvx",
              "args": ["arch-ops-server"]
            }
          }
        }
        ```

        <Warning>
          **Restart Cursor** after saving config changes.
        </Warning>
      </Tab>

      <Tab title="VS Code">
        **Config file location:**

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

        **Add this configuration:**

        ```json mcp_servers.json theme={null}
        {
          "mcpServers": {
            "arch-ops": {
              "command": "uvx",
              "args": ["arch-ops-server"]
            }
          }
        }
        ```

        <Info>
          Requires the MCP extension to be installed from the VS Code marketplace.
        </Info>
      </Tab>

      <Tab title="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:**

        ```json cline_mcp_settings.json theme={null}
        {
          "mcpServers": {
            "arch-ops": {
              "command": "uvx",
              "args": ["arch-ops-server"]
            }
          }
        }
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Verify the connection">
    After restarting your MCP client, verify that arch-ops appears in the connected MCP servers list.

    <Check>
      **Success indicators:**

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

    <Tip>
      Try your first query: "Search the Arch Wiki for systemd basics"
    </Tip>
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Server not appearing in MCP client" icon="circle-xmark">
    **Symptoms:**

    * arch-ops doesn't show in MCP servers list
    * No tools available from arch-ops

    **Solutions:**

    1. **Verify uvx installation:**
       ```bash theme={null}
       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:**
       ```bash theme={null}
       echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | uvx arch-ops-server
       ```

    <Tip>
      Check client logs for detailed error messages (see log locations in next accordion).
    </Tip>
  </Accordion>

  <Accordion title="Where to find logs" icon="file-lines">
    **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:**

    ```bash theme={null}
    # macOS/Linux
    tail -f ~/Library/Logs/Claude/mcp*.log

    # Or use your log location
    ```
  </Accordion>

  <Accordion title="uvx command not found" icon="terminal">
    **Cause:** uv/uvx not installed or not in PATH

    **Solution:**

    1. **Install uv** (see Step 1 above)

    2. **Add to PATH:**
       ```bash theme={null}
       # Add to ~/.bashrc or ~/.zshrc
       export PATH="$HOME/.local/bin:$PATH"

       # Reload shell
       source ~/.bashrc  # or ~/.zshrc
       ```

    3. **Verify:**
       ```bash theme={null}
       which uvx
       uvx --version
       ```
  </Accordion>

  <Accordion title="Permission denied errors" icon="lock">
    **Cause:** Insufficient permissions for installation directory

    **Solutions:**

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

    2. **Check directory permissions:**
       ```bash theme={null}
       ls -la ~/.local/bin
       chmod +x ~/.local/bin/uvx  # if needed
       ```

    3. **Reinstall uv:**
       ```bash theme={null}
       curl -LsSf https://astral.sh/uv/install.sh | sh
       ```
  </Accordion>

  <Accordion title="Connection timeout errors" icon="clock">
    **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:**
       ```bash theme={null}
       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](https://status.archlinux.org/)

    <Warning>
      If timeouts persist, check if your network has strict firewall rules blocking the MCP server process.
    </Warning>
  </Accordion>

  <Accordion title="Python version issues" icon="python">
    **Error:** "Python 3.11+ required"

    **Solution:**

    1. **Check Python version:**
       ```bash theme={null}
       python --version
       python3 --version
       ```

    2. **Install Python 3.11+:**
       ```bash theme={null}
       # 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:**
       ```bash theme={null}
       uvx --python python3.11 arch-ops-server
       ```
  </Accordion>
</AccordionGroup>

<Warning>
  **Still having issues?** Check the [Troubleshooting Guide](/arch-mcp/troubleshoot) for more detailed solutions.
</Warning>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Usage Examples" icon="terminal" href="/arch-mcp/examples">
    Try common use cases and queries
  </Card>

  <Card title="Features Overview" icon="sparkles" href="/arch-mcp/features">
    Learn about all capabilities
  </Card>
</CardGroup>