Code Lens MCP Server
Gemini-powered MCP server for automated code review, analysis, and documentation.
Overview
Code Lens is a Model Context Protocol server that uses Google Gemini to analyze diffs, review pull requests, detect code smells, generate documentation, and verify logic. It exposes 13 tools, 7 resources, and 5 prompts over stdio transport.
Key Features
PR review pipeline — generate diffs, assess impact, detect breaking API changes, and produce review summaries with merge recommendationsFile analysis — load any source file for refactoring suggestions, code smell detection, documentation generation, and natural-language Q&ALogic verification — verify algorithms using Gemini's code execution sandboxStructured outputs — all tools return validated JSON via Zod v4 output schemasWeb search — Google Search with Grounding for up-to-date information retrievalTask lifecycle support — every tool except load_file can run via MCP tasks with polling, cancellation, and progress updates
Requirements
Quick Start
{
"mcpServers" : {
"code-lens" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
}
}
Docker
docker run -i --rm -e GEMINI_API_KEY="your-api-key" ghcr.io/j0hanz/code-lens
Or with Docker Compose:
GEMINI_API_KEY=your-api-key docker compose up
Client Configuration
Install in VS Code
Add to .vscode/mcp.json:
{
"servers" : {
"code-lens" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
}
}
Or install via CLI:
code --add-mcp '{"name":"code-lens","command":"npx","args":["-y","@j0hanz/code-lens-mcp@latest"]}'
For more info, see VS Code MCP docs .
Install in VS Code Insiders
Add to .vscode/mcp.json:
{
"servers" : {
"code-lens" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
}
}
Or install via CLI:
code-insiders --add-mcp '{"name":"code-lens","command":"npx","args":["-y","@j0hanz/code-lens-mcp@latest"]}'
For more info, see VS Code Insiders MCP docs .
Install in Cursor
Add to ~/.cursor/mcp.json:
{
"mcpServers" : {
"code-lens" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
}
}
For more info, see Cursor MCP docs .
Install in Visual Studio
Add to mcp.json:
{
"mcpServers" : {
"code-lens" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
}
}
For more info, see Visual Studio MCP docs .
Install in Goose
{
"mcpServers" : {
"code-lens" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
}
}
For more info, see Goose MCP docs .
Install in LM Studio
{
"mcpServers" : {
"code-lens" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
}
}
For more info, see LM Studio MCP docs .
Install in Claude Desktop Add to claude_desktop_config.json:
{
"mcpServers" : {
"code-lens" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
}
}
For more info, see Claude Desktop MCP docs .
Install in Claude Code claude mcp add code-lens -- npx -y @j0hanz/code-lens-mcp@latest
Or add to config:
{
"mcpServers" : {
"code-lens" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
}
}
For more info, see Claude Code MCP docs .
Install in Windsurf Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers" : {
"code-lens" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
}
}
For more info, see Windsurf MCP docs .
Install in Amp amp mcp add code-lens -- npx -y @j0hanz/code-lens-mcp@latest
Or add to config:
{
"mcpServers" : {
"code-lens" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
}
}
For more info, see Amp MCP docs .
Install in Cline Add to cline_mcp_settings.json:
{
"mcpServers" : {
"code-lens" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
}
}
For more info, see Cline MCP docs .
Install in Codex CLI Add to ~/.codex/config.yaml:
{
"mcpServers" : {
"code-lens" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
}
}
For more info, see Codex CLI MCP docs .
Install in GitHub Copilot Add to .vscode/mcp.json:
{
"servers" : {
"code-lens" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
}
}
For more info, see GitHub Copilot MCP docs .
Install in Warp {
"mcpServers" : {
"code-lens" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
}
}
For more info, see Warp MCP docs .
Install in Kiro Add to .kiro/settings/mcp.json:
{
"mcpServers" : {
"code-lens" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
}
}
For more info, see Kiro MCP docs .
Install in Gemini CLI Add to ~/.gemini/settings.json:
{
"mcpServers" : {
"code-lens" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
}
}
For more info, see Gemini CLI MCP docs .
Install in Zed Add to ~/.config/zed/settings.json:
{
"context_servers" : {
"code-lens" : {
"settings" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ]
}
}
}
}
For more info, see Zed MCP docs .
Install in Augment Add to your VS Code settings.json under augment.advanced:
{
"augment.advanced" : {
"mcpServers" : [
{
"id" : "code-lens" ,
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
]
}
}
For more info, see Augment MCP docs .
Install in Roo Code {
"mcpServers" : {
"code-lens" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
}
}
For more info, see Roo Code MCP docs .
Install in Kilo Code {
"mcpServers" : {
"code-lens" : {
"command" : "npx" ,
"args" : [ "-y" , "@j0hanz/code-lens-mcp@latest" ] ,
"env" : {
"GEMINI_API_KEY" : "your-api-key"
}
}
}
}
For more info, see Kilo Code MCP docs .
Use Cases
PR Review Pipeline
Call generate_diff to capture unstaged or staged changes
Run analyze_pr_impact to assess severity and breaking changes
Run generate_review_summary for a risk rating and merge recommendation
Run detect_api_breaking_changes to check for public API breakage
Run generate_test_plan to produce prioritized test cases
Single-File Analysis
Call load_file to cache a source file
Run refactor_code for structural improvement suggestions
Run detect_code_smells for Fowler-taxonomy anti-patterns
Run generate_documentation to generate JSDoc/TSDoc stubs
Use ask_about_code for natural-language Q&A about the file
Use verify_logic to verify algorithms with code execution
Call generate_diff on a performance-sensitive change
Run analyze_time_space_complexity to detect Big-O degradation
Research
Use web_search for up-to-date documentation or API references via Google Search with Grounding
Architecture
[MCP Client]
│
│ Transport: stdio
▼
[MCP Server: code-lens]
│ Entry: src/index.ts → src/server.ts
│
├── initialize / initialized (lifecycle handshake)
│
├── tools/call ──────────────────────────────────────────────
│ │
│ │ Diff-based tools (require generate_diff first):
│ ├── [generate_diff] Sync — capture git diff
│ ├── [analyze_pr_impact] Flash — severity & impact
│ ├── [generate_review_summary] Flash — risk & merge rec
│ ├── [generate_test_plan] Flash — test cases
│ ├── [analyze_time_space_complexity] Flash — Big-O analysis
│ ├── [detect_api_breaking_changes] Flash — API breakage
│ │
│ │ File-based tools (require load_file first):
│ ├── [load_file] Sync — cache source file
│ ├── [refactor_code] Flash — refactoring
│ ├── [detect_code_smells] Flash — smell detection
│ ├── [generate_documentation] Flash — doc stubs
│ ├── [ask_about_code] Flash — Q&A
│ ├── [verify_logic] Flash — code execution
│ │
│ │ Standalone:
│ └── [web_search] Flash — Google Search
│
├── resources/read ──────────────────────────────────────────
│ ├── [internal://instructions] Server usage guide
│ ├── [internal://tool-catalog] Tool reference
│ ├── [internal://workflows] Workflow sequences
│ ├── [internal://server-config] Runtime config
│ ├── [internal://tool-info/{name}] Per-tool details
│ ├── [internal://diff/current] Cached diff (text/x-patch)
│ └── [internal://file/current] Cached source file
│
├── prompts/get ─────────────────────────────────────────────
│ ├── [get-help] Full server instructions
│ ├── [review-guide] Tool + focus area workflow
│ ├── [select-workflow] Pipeline by change type
│ ├── [analyze-file] File analysis pipeline
│ └── [tool-chain] Tool prerequisite chain
│
└── Capabilities: structured output, tool annotations, notifications
Request Lifecycle
[Client] -- initialize {protocolVersion, capabilities} --> [Server]
[Server] -- {protocolVersion, capabilities, serverInfo} --> [Client]
[Client] -- notifications/initialized --> [Server]
[Client] -- tools/call {name, arguments} --> [Server]
[Server] -- notifications/progress {token, progress, total} --> [Client]
[Server] -- {content, structuredContent, isError?} --> [Client]
Task Lifecycle
generate_diff and load_file are sync-only. All other tools advertise taskSupport: optional.Requestors may supply a task TTL. The server uses that value up to MAX_TASK_TTL_MS, or falls back to TASK_TTL_MS when omitted.
Cancelled tasks remain terminal as cancelled, and tasks/result returns a cancellation-shaped tool result.
MCP Surface
Tool Description Prerequisite Model generate_diffCapture git diff (unstaged/staged) and cache server-side — Sync analyze_pr_impactAssess severity, categories, breaking changes, rollback complexity generate_diffFlash generate_review_summaryPR summary, risk rating, merge recommendation generate_diffFlash generate_test_planPrioritized test cases and coverage guidance generate_diffFlash analyze_time_space_complexityBig-O complexity analysis and degradation detection generate_diffFlash detect_api_breaking_changesDetect breaking API/interface changes generate_diffFlash load_fileCache a source file for analysis tools — Sync refactor_codeComplexity, duplication, naming, grouping suggestions load_fileFlash detect_code_smellsStructural code smells (Fowler taxonomy) load_fileFlash generate_documentationJSDoc/TSDoc/docstring stubs for public exports load_fileFlash ask_about_codeNatural-language Q&A about a cached file load_fileFlash verify_logicVerify algorithms via Gemini code execution sandbox load_fileFlash web_searchGoogle Search with Grounding — Flash
Resources
URI Description MIME internal://instructionsComplete server usage instructions text/markdowninternal://tool-catalogTool reference: models, params, outputs, data flow text/markdowninternal://workflowsRecommended workflows and tool sequences text/markdowninternal://server-configRuntime configuration and limits text/markdowninternal://tool-info/{toolName}Per-tool details (parameterized) text/markdowninternal://diff/currentMost recently generated diff text/x-patchinternal://file/currentMost recently loaded source file text/plain
Prompts
Prompt Description get-helpFull server instructions: capabilities, tools, resources, constraints review-guideWorkflow guide for a specific tool and focus area select-workflowRecommended tool pipeline based on change type analyze-fileGoal-based tool pipeline for single-file analysis tool-chainFull prerequisite chain for a given tool
MCP Capabilities
All tools expose MCP tool annotations:
Annotation Used readOnlyHintYes destructiveHintYes idempotentHintYes openWorldHintYes
Structured Output
All Gemini-powered tools return validated structuredContent alongside text content, using Zod v4 output schemas.
Configuration
Variable Default Description GEMINI_API_KEY— Required. Gemini API key. Falls back to GOOGLE_API_KEY.GEMINI_MODELgemini-3-flash-previewOverride the default Gemini model for all tools. MAX_DIFF_CHARS120000Maximum diff size in characters. MAX_CONCURRENT_CALLS10Maximum concurrent Gemini API calls. MAX_CONCURRENT_BATCH_CALLS2Maximum concurrent batch Gemini calls. MAX_CONCURRENT_CALLS_WAIT_MS2000Wait timeout for concurrency semaphore. TASK_TTL_MS300000Default task result retention in milliseconds when the request does not specify task.ttl. MAX_TASK_TTL_MS3600000Upper bound for request-provided task TTL. Set to 0 to remove the cap. GEMINI_BATCH_MODEoffEnable Gemini batch mode. GEMINI_HARM_BLOCK_THRESHOLDBLOCK_NONESafety filter threshold (BLOCK_NONE, BLOCK_ONLY_HIGH, BLOCK_MEDIUM_AND_ABOVE, BLOCK_LOW_AND_ABOVE). GEMINI_DIFF_CACHE_ENABLEDfalseEnable Gemini context caching for large diffs. GEMINI_DIFF_CACHE_TTL_S3600Cache TTL in seconds (when caching is enabled).
CLI Flags
npx @j0hanz/code-lens-mcp@latest --model gemini-2.5-flash --max-diff-chars 200000
Flag Env Equivalent --model, -mGEMINI_MODEL--max-diff-charsMAX_DIFF_CHARS
Security
Control Status Input validation Zod v4 schema validation on all tool inputs Path safety load_file restricts paths to workspace rootStdout safety Logs to stderr; stdout reserved for MCP protocol Non-root container Docker runs as dedicated mcp user
Development
npm install
npm run build
npm run dev
npm run dev:run
npm run start
npm run type-check
npm run lint
npm run test
npm run format
npm run inspector
npm run knip
Build and Release
CI: .github/workflows/release.yml
Docker: Multi-stage build (Dockerfile) with node:24-alpine
Docker Compose: docker-compose.yml
npm: Published as @j0hanz/code-lens-mcp
Troubleshooting
Missing API key : Set GEMINI_API_KEY or GOOGLE_API_KEY in your environment or client config env block."E_NO_DIFF" errors : Call generate_diff before running any diff-based review tool."E_NO_FILE" errors : Call load_file before running any file analysis tool.Large diffs truncated : Increase MAX_DIFF_CHARS (default: 120,000 characters).Stdout noise : Ensure no other processes write to stdout; the server uses stdio transport.
Credits
Contributing and License
MIT License. See LICENSE for details.
Contributions welcome via pull requests .
