Pyscn

What pyscn MCP server does

pyscn MCP server brings structural analysis of Python repositories into MCP-compatible coding agents. Its analyses cover five broad areas: code complexity, unused or unreachable code, duplicate and structurally similar code, dependency and architecture relationships, and class design. Results contribute to a repository health score from 0 to 100 with an A–F grade.

The server exposes the same analysis family available through the pyscn command-line tool. Agents can use it to inspect a codebase, identify refactoring targets, review architectural structure, or produce quality information suitable for development and CI workflows.

How it works

The server runs as a local stdio MCP process. A client starts pyscn-mcp, and the process makes pyscn analyses available as MCP operations. The underlying analyzer is implemented with Go and tree-sitter and is intended for Python source code.

Analysis can examine function and executable-class complexity, including cyclomatic and cognitive complexity. It can detect dead code, Type 1–4 clones, circular imports, architecture-layer violations, module communities, coupling, and low class cohesion. File and directory hotspots help an agent prioritize areas for review rather than treating every finding equally.

pyscn also supports a separate command-line workflow. The CLI can generate HTML or JSON reports, run selected analyses, and perform fast quality checks with configurable thresholds. The MCP server is useful when those decisions need to happen inside an agent conversation instead of as a manually invoked command.

Setup and configuration

The documented launch command uses uvx:

claude mcp add pyscn-mcp uvx -- pyscn-mcp

For Cursor or Claude Desktop, add a server entry whose command is uvx and whose argument is pyscn-mcp. A configuration file can be supplied through the PYSCN_CONFIG environment variable:

{
  "mcpServers": {
    "pyscn-mcp": {
      "command": "uvx",
      "args": ["pyscn-mcp"],
      "env": {
        "PYSCN_CONFIG": "/path/to/.pyscn.toml"
      }
    }
  }
}

The configuration file may be .pyscn.toml, or the settings can be placed under [tool.pyscn] in pyproject.toml. Supported examples include a maximum complexity threshold, a minimum dead-code severity, and an output directory. pyscn init can generate a complete configuration file when using the CLI.

Claude Code also has a plugin installation path that sets up the MCP server together with the project’s Agent Skills. The MCP setup is optional; the skills provide a separate way to guide agents on when to run health checks, refactoring analysis, architecture reviews, and CI-oriented reports.

Tools and capabilities

• Analyze Python complexity using cyclomatic and cognitive measures.
• Find dead or unreachable code.
• Detect copied and structurally similar code, including Type 1–4 clones.
• Inspect circular imports, dependency relationships, and architecture-layer violations.
• Identify module communities and file or directory hotspots.
• Evaluate class coupling with CBO and cohesion with LCOM4.
• Produce an overall 0–100 health score with an A–F grade.
• Use configured thresholds and project settings through pyscn configuration.

Limitations and notes

pyscn is the Python analyzer in the broader polyscan project; JavaScript, TypeScript, Go, Rust, and C++ analysis uses the separate polyscan command rather than this server. The MCP package is intended for MCP clients, while HTML and JSON report generation and fast pass/fail checks are described as CLI capabilities.

On Intel Macs, the PyPI wheels are not available for the package. The documented alternatives are Homebrew or installing the command from source with Go. This limitation concerns package installation rather than the analysis model itself.

The project is released under the MIT License.