Installation

Quick Start

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

sudo pacman -S uv

brew install uv

scoop install uv

pip install uv

cargo install uv

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

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Verify installation: uv --version

Additional Installation Methods

Manual Installation

Download pre-built binaries from the GitHub Releases page:

Download the appropriate binary for your operating system
Extract the binary to a directory in your PATH
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

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

Configure your MCP client

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

Claude Desktop
Cursor
VS Code
Cline

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.

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.

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.

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"]
    }
  }
}

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:

Verify uvx installation:
which uvx uvx --version
Check config file syntax:
- Ensure JSON is valid (no trailing commas)
- Verify file path is correct for your OS
Restart client completely:
- Quit application (not just close window)
- Relaunch and check logs

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 PATHSolution:

Install uv (see Step 1 above)

Add to PATH:

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

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

Verify:
which uvx uvx --version

Permission denied errors

Cause: Insufficient permissions for installation directorySolutions:

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

Check directory permissions:

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

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:

Test network connectivity:

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

Check firewall rules:
- Ensure MCP server can make outbound HTTPS requests
- Check corporate proxy settings if applicable
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:

Check Python version:
python --version python3 --version

Install Python 3.11+:

# Arch Linux
sudo pacman -S python

# macOS (Homebrew)
brew install [email protected]

# Ubuntu/Debian
sudo apt install python3.11

Verify uv uses correct Python:

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

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

Getting started

Features

Development

Installation

Quick Start

Manual Installation

Conda/Mamba

STDIO Transport (Recommended)

HTTP/SSE Transport (Smithery)

Troubleshooting

Next Steps

Usage Examples

Features Overview

​Quick Start

​Manual Installation

​Conda/Mamba

​STDIO Transport (Recommended)

​HTTP/SSE Transport (Smithery)

​Troubleshooting

​Next Steps

Usage Examples

Features Overview

Quick Start

Manual Installation

Conda/Mamba

STDIO Transport (Recommended)

HTTP/SSE Transport (Smithery)

Troubleshooting

Next Steps