# pyscn

Inspects Python codebases for dead code, complexity, and architectural cycles directly inside AI sessions. Useful for structural audits and refactoring.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 1096
- Author: ludo-technologies
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ludo-technologies/pyscn
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/pyscn

## What it does

Built with Go and tree-sitter, the engine scans code at over 100,000 lines per second. It assigns the repository an overall health score from 0 to 100 with an A to F grade. The server analyzes cyclomatic and cognitive complexity in functions, uncovers unreachable dead code, and flags four types of code clones.

On the architectural side, pyscn identifies circular imports and verifies boundary rules for clean, hexagonal, or MVC layers. It also evaluates class coupling with CBO and cohesion via LCOM4. Custom analysis rules load from `.pyscn.toml`, configured with the `PYSCN_CONFIG` environment variable.

Prebuilt wheels on PyPI support Apple Silicon only. Intel Mac systems cannot run the tool via `uvx` after x86_64 wheel support ended in v1.5.1, requiring a Homebrew install or manual Go compilation.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `PYSCN_CONFIG` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env PYSCN_CONFIG=<PYSCN_CONFIG> --transport stdio pyscn -- uvx pyscn-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from pyscn-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add pyscn --env PYSCN_CONFIG=<PYSCN_CONFIG> -- uvx pyscn-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from pyscn-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "pyscn": {
            "command": "uvx",
            "args": [
                "pyscn-mcp"
            ],
            "env": {
                "PYSCN_CONFIG": "<PYSCN_CONFIG>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from pyscn-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "pyscn": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "pyscn-mcp"
            ],
            "env": {
                "PYSCN_CONFIG": "<PYSCN_CONFIG>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from pyscn-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e PYSCN_CONFIG=<PYSCN_CONFIG> pyscn uvx pyscn-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from pyscn-mcp <command>

## When to use it
- find circular imports and architectural boundary violations
- spot unreachable dead code across modules
- detect structural code clones and copy-pasted blocks
- calculate cyclomatic and cognitive complexity metrics

## Example prompts
- Analyze the code quality in the `app/` folder
- Find duplicate code across the project and suggest refactoring
- Check for circular imports and module coupling

## Similar
- [Front-End Checklist](https://affpapa.org/en/nevibecode/mcp/front-end-checklist.md) — MCP server · ★ 74559
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [Serena MCP: the IDE for your agent](https://affpapa.org/en/nevibecode/mcp/serena-mcp-the-ide-for-your-agent.md) — MCP server · ★ 30677
- [Repomix](https://affpapa.org/en/nevibecode/mcp/repomix.md) — MCP server · ★ 29027
- [Repowise](https://affpapa.org/en/nevibecode/mcp/repowise.md) — MCP server · ★ 7891
- [sem](https://affpapa.org/en/nevibecode/mcp/sem.md) — MCP server · ★ 3422

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md