๐ Code Lens MCP Server
A Gemini-powered MCP server for automated code review, analysis, and documentation.
๐ Quick Start
Prerequisites
Configuration
{
"mcpServers": {
"code-lens": {
"command": "npx",
"args": ["-y", "@j0hanz/code-lens-mcp@latest"],
"env": {
"GEMINI_API_KEY": "your-api-key"
}
}
}
}
Docker Installation
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
โจ Features
- PR review pipeline: Generate diffs, assess impact, detect breaking API changes, and produce review summaries with merge recommendations.
- File analysis: Load any source file for refactoring suggestions, code smell detection, documentation generation, and natural-language Q&A.
- Logic verification: Verify algorithms using Gemini's code execution sandbox.
- Structured outputs: All tools return validated JSON via Zod v4 output schemas.
- Web search: Google Search with Grounding for up-to-date information retrieval.
- Task lifecycle support: Every tool except
load_file can run via MCP tasks with polling, cancellation, and progress updates.
๐ฆ Installation
Install in Different Editors
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.
๐ป Usage Examples
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.
Performance Audit
- 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.
๐ Documentation
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
Tools
| Tool |
Description |
Prerequisite |
Model |
generate_diff |
Capture git diff (unstaged/staged) and cache server-side |
โ |
Sync |
analyze_pr_impact |
Assess severity, categories, breaking changes, rollback complexity |
generate_diff |
Flash |
generate_review_summary |
PR summary, risk rating, merge recommendation |
generate_diff |
Flash |
generate_test_plan |
Prioritized test cases and coverage guidance |
generate_diff |
Flash |
analyze_time_space_complexity |
Big-O complexity analysis and degradation detection |
generate_diff |
Flash |
detect_api_breaking_changes |
Detect breaking API/interface changes |
generate_diff |
Flash |
load_file |
Cache a source file for analysis tools |
โ |
Sync |
refactor_code |
Complexity, duplication, naming, grouping suggestions |
load_file |
Flash |
detect_code_smells |
Structural code smells (Fowler taxonomy) |
load_file |
Flash |
generate_documentation |
JSDoc/TSDoc/docstring stubs for public exports |
load_file |
Flash |
ask_about_code |
Natural-language Q&A about a cached file |
load_file |
Flash |
verify_logic |
Verify algorithms via Gemini code execution sandbox |
load_file |
Flash |
web_search |
Google Search with Grounding |
โ |
Flash |
Resources
| URI |
Description |
MIME |
internal://instructions |
Complete server usage instructions |
text/markdown |
internal://tool-catalog |
Tool reference: models, params, outputs, data flow |
text/markdown |
internal://workflows |
Recommended workflows and tool sequences |
text/markdown |
internal://server-config |
Runtime configuration and limits |
text/markdown |
internal://tool-info/{toolName} |
Per-tool details (parameterized) |
text/markdown |
internal://diff/current |
Most recently generated diff |
text/x-patch |
internal://file/current |
Most recently loaded source file |
text/plain |
Prompts
| Prompt |
Description |
get-help |
Full server instructions: capabilities, tools, resources, constraints |
review-guide |
Workflow guide for a specific tool and focus area |
select-workflow |
Recommended tool pipeline based on change type |
analyze-file |
Goal-based tool pipeline for single-file analysis |
tool-chain |
Full prerequisite chain for a given tool |
MCP Capabilities
Tool Annotations
All tools expose MCP tool annotations:
| Annotation |
Used |
readOnlyHint |
Yes |
destructiveHint |
Yes |
idempotentHint |
Yes |
openWorldHint |
Yes |
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_MODEL |
gemini-3-flash-preview |
Override the default Gemini model for all tools. |
MAX_DIFF_CHARS |
120000 |
Maximum diff size in characters. |
MAX_CONCURRENT_CALLS |
10 |
Maximum concurrent Gemini API calls. |
MAX_CONCURRENT_BATCH_CALLS |
2 |
Maximum concurrent batch Gemini calls. |
MAX_CONCURRENT_CALLS_WAIT_MS |
2000 |
Wait timeout for concurrency semaphore. |
TASK_TTL_MS |
300000 |
Default task result retention in milliseconds when the request does not specify task.ttl. |
MAX_TASK_TTL_MS |
3600000 |
Upper bound for request-provided task TTL. Set to 0 to remove the cap. |
GEMINI_BATCH_MODE |
off |
Enable Gemini batch mode. |
GEMINI_HARM_BLOCK_THRESHOLD |
BLOCK_NONE |
Safety filter threshold (BLOCK_NONE, BLOCK_ONLY_HIGH, BLOCK_MEDIUM_AND_ABOVE, BLOCK_LOW_AND_ABOVE). |
GEMINI_DIFF_CACHE_ENABLED |
false |
Enable Gemini context caching for large diffs. |
GEMINI_DIFF_CACHE_TTL_S |
3600 |
Cache 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, -m |
GEMINI_MODEL |
--max-diff-chars |
MAX_DIFF_CHARS |
๐ง Technical Details
Security
| Control |
Status |
| Input validation |
Zod v4 schema validation on all tool inputs |
| Path safety |
load_file restricts paths to workspace root |
| Stdout 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
๐ License
MIT License. See LICENSE for details.
Contributions welcome via pull requests.
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