mcp server

Mago-MCP

MCP server that gives AI assistants Mago's PHP linter, formatter, and static analyser.

hussainbiedouh/Mago-MCPcommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

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

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "hussainbiedouh-mago-mcp": {
      "command": "uvx",
      "args": [
        "mago-mcp"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 28, 2026

Mago MCP Server

An MCP server that gives AI assistants Mago, the PHP linter, formatter and static analyser, as callable tools.

Tools

Tool	What it runs
`mago_lint`	`mago lint` on a PHP file or directory
`mago_format`	`mago format` on a PHP file or directory
`mago_analyze`	`mago analyze` on a PHP file or directory

mago_lint

Argument	Type	Default	Description
`path`	string	required	PHP file or directory to lint
`fix`	boolean	`false`	Try to fix the issues that were found

mago_format

Argument	Type	Default	Description
`path`	string	required	PHP file or directory to format
`check`	boolean	`false`	Report whether formatting is needed, change nothing
`diff`	boolean	`false`	Show the differences that would be made

mago_analyze

Argument	Type	Default	Description
`path`	string	required	PHP file or directory to analyse

The server also exposes a mago://docs resource listing the available tools.

Requirements

Python 3.10 or newer
Mago, either on your PATH or pointed at by the MAGO_EXE environment variable

Install Mago from its releases page, or with Cargo:

cargo install mago

Install

git clone https://github.com/hussainbiedouh/Mago-MCP.git
cd Mago-MCP

python -m venv .venv
.venv\Scripts\activate        # Windows
source .venv/bin/activate     # macOS and Linux

pip install -e .

Add it to your client

The server speaks stdio, which means the client starts it and stops it with the session. Ready-made snippets are in mcp-configs/, and each client expects a different key:

Client	Config file	Key
OpenCode	`~/.config/opencode/opencode.jsonc`	`mcp.servers`
Claude Desktop	`claude_desktop_config.json`	`mcpServers`
Cursor	`~/.cursor/mcp.json`	`mcpServers`
VS Code	`.vscode/mcp.json`	`servers`

For OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "mago-mcp": {
        "type": "local",
        "command": [
          "C:\\path\\to\\Mago-MCP\\.venv\\Scripts\\python.exe",
          "-m",
          "mago_mcp"
        ],
        "environment": {
          "PYTHONIOENCODING": "utf-8"
        }
      }
    }
  }
}

Point the command at the full path of the interpreter. The PATH a client inherits is not always the PATH in your shell, and python can resolve to a different install than the one you tested with.

The same file will not work across clients, because the key differs. mcp-client-config has the full table and what each failure mode looks like.

Choosing which mago to run

The server looks for the executable in this order:

the MAGO_EXE environment variable
mago or mago.exe on PATH
~/.config/opencode/tools/mago.exe

If none of them turn up an executable, the tool call comes back with an error telling you to install Mago.

Development

There is no test suite yet. The check that matters is the linter:

pip install ruff
ruff check .

License

MIT