Skip to main content
The aislop MCP server exposes aislop’s core capabilities as Model Context Protocol (MCP) tools, making them available directly inside AI coding environments like Claude Desktop, Cursor, and OpenAI Codex. Once configured, your AI agent can scan files, auto-fix issues, explain individual rules, and capture baselines without leaving the editor or switching to a terminal.

​
What the MCP server provides

The server registers four tools that the AI agent can call during a coding session:

aislop_scan

Runs aislop scan on a path and returns structured findings. The agent sees rule IDs, messages, severity, and the overall score.

aislop_fix

Applies mechanical auto-fixes — unused imports, narrative comments, dead code, formatting — and reports what was changed.

aislop_why

Explains why a specific rule exists, what pattern it catches, and how to resolve a finding, giving the agent full context for non-mechanical fixes.

aislop_baseline

Captures the current score as a baseline. Subsequent hook runs or scans compare against this baseline to detect regressions.

​
Quick start (no install)

The fastest way to add the MCP server is with npx -y aislop-mcp, which downloads and runs the server on demand without a global install. 
// Claude Desktop config or ~/.cursor/mcp.json
{
  "mcpServers": {
    "aislop": {
      "command": "npx",
      "args": ["-y", "aislop-mcp"]
    }
  }
}

​
Configuration by environment

Open your Claude Desktop configuration file and add the aislop entry under mcpServers:
// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "aislop": {
      "command": "npx",
      "args": ["-y", "aislop-mcp"]
    }
  }
}
Restart Claude Desktop after saving. The aislop tools appear automatically in the tools panel.

​
Using a globally installed binary

If you have installed aislop-mcp globally (npm i -g aislop-mcp), reference the binary directly instead of using npx. This avoids the package resolution step on every server start. 
{
  "mcpServers": {
    "aislop": {
      "command": "aislop-mcp"
    }
  }
}
Using npx -y aislop-mcp always picks up the latest published version of the MCP server automatically — no version to bump and no global install to maintain.

​
How agents use the tools

Once the server is running, the AI agent can call the tools during a session. A typical workflow looks like this:
1

Agent generates or edits code

The agent writes a function, refactors a module, or makes changes across several files.
2

Agent calls aislop_scan

The agent scans the modified path and receives structured findings: rule IDs, line numbers, messages, and the overall score.
3

Agent calls aislop_fix

For mechanical issues (unused imports, narrative comments, dead code), the agent applies auto-fixes directly.
4

Agent calls aislop_why (if needed)

For findings that require context-specific judgment, the agent calls aislop_why to understand the rule before deciding how to resolve it.
5

Agent calls aislop_baseline

After resolving issues, the agent captures a new baseline so future runs measure regression against the current state.
The MCP server shells out to the aislop CLI. Make sure aislop is installed and available on the PATH used by your environment, or install it globally with npm i -g aislop before starting the server.