Installation

System requirements and install options for mage-agent.

​

Requirements

• A Mage Pro cluster (URL + account credentials)
• Your chosen AI client
• Python 3.10 or newer for PyPI or source installation; bundled installers and the Claude Desktop extension include the Mage Agent executable

​

Download from Mage Pro

In Mage Pro, open Settings > Plugins > Mage Agent to download the latest Mage Agent installer for Claude Code or OpenAI Codex CLI.

The page lists the latest GitHub release assets for macOS and Windows, including file sizes and checksums. Download links use GitHub’s stable latest-release asset URLs, so Mage Pro does not need source changes when release tags or asset URLs change. Use the download that matches your operating system and AI coding client, then follow the prompts from the installer.

​

Claude Desktop extension

Claude Desktop uses a separate .mcpb extension for macOS or Windows. It includes the standalone Mage Agent executable and does not require Python or Claude Code. See the plugin installation guide for package selection and setup. The Claude Code .pkg and .zip installers are for Claude Code.

​

Install from PyPI

pip install mage-agent

We recommend installing inside a virtual environment:

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install mage-agent

Verify:

mage-agent --version

​

Install from source

git clone https://github.com/mage-ai/mage-agent.git
cd mage-agent
python -m venv .venv
source .venv/bin/activate
pip install -e .

​

IDE PATH requirement

When you configure your IDE to launch mage-agent mcp, the IDE may use a different PATH than your terminal. If the MCP server fails to start, use the absolute path to the executable:

which mage-agent   # e.g. /Users/you/.venv/bin/mage-agent

Then update your IDE config:

{
  "mcpServers": {
    "mage-agent": {
      "command": "/Users/you/.venv/bin/mage-agent",
      "args": ["mcp"]
    }
  }
}