MCP server that scans your codebase for TODOs, FIXMEs, code complexity, file stats, dependency analysis, and generates a health report with a letter grade. Zero config, zero API keys.

Install

npx codescan-mcp

No config files. No API keys. Works on any local project directory.

Tools

`scan_todos` — Find all TODOs, FIXMEs, HACKs

"Find all TODOs in this project"
"Show me every FIXME and HACK in my codebase"
"What TODOs are in /path/to/project?"

Scans every code file, returns tag, file, line number, and text. Groups by tag type.

`project_stats` — Codebase statistics

"How many lines of code are in this project?"
"Show file count by language"
"What are the largest files?"

Files by extension, line counts, size, directory breakdown, largest files ranked.

`find_complex_files` — Complexity detector

"Find files over 300 lines"
"Which files have the deepest nesting?"
"Show me complex files that need refactoring"

Flags long files, deep nesting, and long functions. Configurable threshold.

`check_dependencies` — Dependency analysis

"How many dependencies does this project have?"
"Is there a lockfile?"
"List all npm packages this project uses"

Supports: package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml.

`health_report` — Full health report with letter grade

"Give me a health report for this project"
"Grade this codebase"
"How healthy is this project?"

Combines all analyses into a single report with an A-F grade, scores, and actionable recommendations.

Configuration

Claude Desktop / Claude Code

{
  "mcpServers": {
    "codescan": {
      "command": "npx",
      "args": ["codescan-mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "codescan": {
      "command": "npx",
      "args": ["codescan-mcp"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "codescan": {
      "command": "npx",
      "args": ["codescan-mcp"]
    }
  }
}

What It Scans

35+ file types: TypeScript, JavaScript, Python, Go, Rust, Java, C/C++, Ruby, PHP, Swift, Kotlin, Vue, Svelte, and more
Smart ignore: Skips node_modules, .git, dist, build, pycache, vendor, and other non-source directories
Performance: Handles projects up to 5,000 files, skips files over 500KB