pyscn — Claude Code MCP server: what it does, how to install
Inspects Python codebases for dead code, complexity, and architectural cycles directly inside AI sessions. Useful for structural audits and refactoring.
claude mcp add --env PYSCN_CONFIG=<PYSCN_CONFIG> --transport stdio pyscn -- uvx pyscn-mcpWhat pyscn 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.
What it helps with
- 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 for the agent
- Analyze the code quality in the
app/folder - Find duplicate code across the project and suggest refactoring
- Check for circular imports and module coupling
How to install pyscn
Platform CLI
claude mcp add --env PYSCN_CONFIG=<PYSCN_CONFIG> --transport stdio pyscn -- uvx pyscn-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from pyscn-mcp <command>
Platform CLI
codex mcp add pyscn --env PYSCN_CONFIG=<PYSCN_CONFIG> -- uvx pyscn-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from pyscn-mcp <command>
Config file
{
"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>
Config file
{
"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>
Platform CLI
gemini mcp add -e PYSCN_CONFIG=<PYSCN_CONFIG> pyscn uvx pyscn-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from pyscn-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about pyscn
How to install pyscn in Claude Code?
Run claude mcp add pyscn -- uvx pyscn-mcp. To pass a custom configuration file path, use claude mcp add --env PYSCN_CONFIG=<PYSCN_CONFIG> --transport stdio pyscn -- uvx pyscn-mcp.
What does pyscn inspect in Python codebases?
The server checks cyclomatic and cognitive complexity, locates unreachable code, and catches structural clones. It also maps circular dependencies and measures class coupling through CBO and LCOM4.
Can pyscn run on Intel-based Macs?
PyPI wheels dropped x86_64 support in version v1.5.1, so uvx fails on Intel Macs. On those machines, install the binary via brew install pyscn or build it with go install github.com/ludo-technologies/pyscn/cmd/pyscn@latest.
