@vibesnipe/code-review-mcp

Version: 1.0.0

An MCP (Model Context Protocol) server that provides a powerful tool to perform code reviews using various Large Language Models (LLMs). This server is designed to be seamlessly integrated with AI coding assistants like Anthropic's Claude Code, Cursor, Windsurf, or other MCP-compatible clients.

> Note: This tool was initially created for Claude Code but has since been expanded to support other AI IDEs and Claude Desktop. See the integration guides for Claude Code, Cursor, and Windsurf.

It analyzes `git diff` output for staged changes, differences from HEAD, or differences between branches, providing contextualized reviews based on your task description and project details.

Features

• Reviews git diffs (staged changes, current HEAD, branch differences).
• Integrates with Google Gemini, OpenAI, and Anthropic models through the Vercel AI SDK.
• Allows specification of task description, review focus, and overall project context for tailored reviews.
• Outputs reviews in clear, actionable markdown format.
• Designed to be run from the root of any Git repository you wish to analyze.
• Easily installable and runnable via `npx` for immediate use.

Compatibility

• Node.js: Version 18 or higher is required.
• Operating Systems: Works on Windows, macOS, and Linux.
• Git: Version 2.20.0 or higher recommended.

Prerequisites

• Node.js: Version 18 or higher is required.
• Git: Must be installed and accessible in your system's PATH. The server executes `git` commands.
• API Keys for LLMs: You need API keys for the LLM providers you intend to use. These should be set as environment variables:

These can be set globally in your environment or, conveniently, in a `.env` file placed in the root of the project you are currently reviewing. The server will automatically try to load it.

Installation & Usage

The primary way to use this server is with `npx`, which ensures you're always using the latest version without needing a global installation.

Recommended: Using with `npx`

1. Navigate to Your Project:

Open your terminal and change to the root directory of the Git repository you want to review.

cd /path/to/your-git-project

2. Run the MCP Server:

Execute the following command:

npx -y @vibesnipe/code-review-mcp

This command will download (if not already cached) and run the `@vibesnipe/code-review-mcp` server. You should see output in your terminal similar to:

`[MCP Server] Code Reviewer MCP Server is running via stdio and connected to transport.`

The server is now running and waiting for an MCP client (like Claude Code, Cursor, or Windsurf) to connect.

Installing via Smithery

To install code-review-mcp for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @praneybehl/code-review-mcp --client claude

Integration with Claude Code

Once the `claude-code-review-mcp` server is running (ideally via `npx` from your project's root):

1. Add as an MCP Server in Claude Code:

In a separate terminal where Claude Code is running (or will be run), configure it to use this MCP server.

The command to run the server (as used by Claude Code) would be `code-review-mcp` if installed globally and in PATH, or the `npx ...` command if you prefer Claude Code to always fetch it.

To add it to Claude Code:

claude mcp add code-reviewer -s  -e GOOGLE_API_KEY="key" -- code-review-mcp

If you want Claude Code to use `npx` (which is a good practice to ensure version consistency if you don't install globally):

claude mcp add code-reviewer -s  -e GOOGLE_API_KEY="key" -- npx -y @vibesnipe/code-review-mcp

This tells Claude Code how to launch the MCP server when the "code-reviewer" toolset is requested. This configuration can be project-specific (saved in `.claude/.mcp.json` in your project) or user-specific (global Claude Code settings).

2. Use Smart Slash Commands in Claude Code:

Create custom slash command files in your project's `.claude/commands/` directory to easily invoke the review tool. The package includes several example commands in the `examples/claude-commands/` directory that you can copy to your project.

These improved slash commands don't require you to manually specify task descriptions or project context - they leverage Claude Code's existing knowledge of your project and the current task you're working on.

Example invocation using a slash command in Claude Code:

claude > /project:review-staged-claude

No additional arguments needed! Claude will understand what you're currently working on and use that as context for the review.

For commands that require arguments (like `review-branch-custom-gemini.md` which uses a custom branch name), you can pass them directly after the command:

claude > /project:review-branch-custom-gemini main

This will pass "main" as the $ARGUMENTS_BASE_BRANCH parameter.

Integration with Modern AI IDEs

Cursor Integration

Cursor is a popular AI-powered IDE based on VS Code that supports MCP servers. Here's how to integrate the code review MCP server with Cursor:

1. Configure Cursor's Rules for Code Review:

Create or open the `.cursor/rules/project.mdc` file in your project and add the following section:

## Slash Commands

   /review-staged: Use the perform_code_review tool from the code-reviewer MCP server to review staged changes. Use anthropic provider with claude-3-7-sonnet-20250219 model. Base the task description on our current conversation context and focus on code quality and best practices.

   /review-head: Use the perform_code_review tool from the code-reviewer MCP server to review all uncommitted changes (HEAD). Use openai provider with o3 model. Base the task description on our current conversation context and focus on code quality and best practices.

   /review-security: Use the perform_code_review tool from the code-reviewer MCP server to review staged changes. Use anthropic provider with claude-3-5-sonnet-20241022 model. Base the task description on our current conversation context and specifically focus on security vulnerabilities, input validation, and secure coding practices.

2. Add the MCP Server in Cursor:

"code-reviewer": {
     "command": "npx",
     "args": ["-y", "@vibesnipe/code-review-mcp"],
     "env": {
       "GOOGLE_API_KEY": "your-google-api-key",
       "OPENAI_API_KEY": "your-openai-api-key",
       "ANTHROPIC_API_KEY": "your-anthropic-api-key"
     }
   }

4. Using the Commands:

In Cursor's AI chat interface, you can now simply type:

/review-staged

And Cursor will use the claude-code-review-mcp server to perform a code review of your staged changes.

Windsurf Integration

Windsurf (formerly Codeium) is another advanced AI IDE that supports custom workflows via slash commands. Here's how to integrate with Windsurf:

1. Configure the MCP Server in Windsurf:

"code-reviewer": {
     "command": "npx",
     "args": ["-y", "@vibesnipe/code-review-mcp"],
     "env": {
       "GOOGLE_API_KEY": "your-google-api-key",
       "OPENAI_API_KEY": "your-openai-api-key",
       "ANTHROPIC_API_KEY": "your-anthropic-api-key"
     }
   }

3. Create Workflows for Code Review:

Windsurf supports workflows that can be invoked via slash commands. Create a file in `.windsurf/workflows/review-staged.md`:

# Review Staged Changes
   
   Perform a code review on the currently staged changes in the repository.
   
   ## Step 1
   
   Use the perform_code_review tool from the code-reviewer MCP server with the following parameters:

{

"target": "staged",

"llmProvider": "anthropic",

"modelName": "claude-3-7-sonnet-20250219",

"taskDescription": "The task I am currently working on in this codebase",

"reviewFocus": "General code quality, security best practices, and performance considerations",

"projectContext": "This project is being developed in Windsurf. Please review the code carefully for any issues."

}

// Code block

Similarly, create workflows for other review types as needed.

4. Using the Workflows:

In Windsurf's Cascade interface, you can invoke these workflows with:

/review-staged

Windsurf will then execute the workflow, which will use the claude-code-review-mcp server to perform the code review.

Tool Provided by this MCP Server

`perform_code_review`

Description:

Performs a code review using a specified Large Language Model on git changes within the current Git repository. This tool must be run from the root directory of the repository being reviewed.

Input Schema (Parameters):

The tool expects parameters matching the `CodeReviewToolParamsSchema`:

• `target` (enum: `'staged'`, `'HEAD'`, `'branch_diff'`):

Specifies the set of changes to review.

• `taskDescription` (string):

A clear and concise description of the task, feature, or bugfix that led to the code changes. This provides crucial context for the LLM reviewer. (e.g., "Implemented password reset functionality via email OTP.")

• `llmProvider` (enum: `'google'`, `'openai'`, `'anthropic'`):

The Large Language Model provider to use for the review.

• `modelName` (string):

The specific model name from the chosen provider. Examples:

*(Ref: https://ai-sdk.dev/providers/ai-sdk-providers/google-generative-ai#model-capabilities)*

*(Ref: https://ai-sdk.dev/providers/ai-sdk-providers/openai#model-capabilities)*

*(Ref: https://ai-sdk.dev/providers/ai-sdk-providers/anthropic#model-capabilities)*

Ensure the model selected is available via the Vercel AI SDK and your API key has access.

Note: Model names often change as providers release new versions. Always check the latest documentation from your provider and update the model names accordingly.

• `reviewFocus` (string, optional but recommended):

Specific areas, concerns, or aspects you want the LLM to concentrate on during the review. (e.g., "Focus on thread safety in concurrent operations.", "Pay special attention to input validation and sanitization.", "Check for adherence to our internal style guide for React components.").

• `projectContext` (string, optional but recommended):

General background information about the project, its architecture, key libraries, coding standards, or any other context that would help the LLM provide a more relevant and insightful review. (e.g., "This is a high-performance microservice using Rust and Actix. Low latency is critical.", "The project follows Clean Architecture principles. Ensure new code aligns with this.").

• `diffBase` (string, optional):

Required if `target` is `'branch_diff'. Specifies the base branch (e.g., `'main'`, `'develop'`) or a specific commit SHA to compare the current HEAD against.

• `maxTokens` (number, optional):

Maximum number of tokens to use for the LLM response. Defaults to 32000 if not specified. Use this parameter to optimize for faster, less expensive responses (lower value) or more comprehensive reviews (higher value).

Note: In v0.11.0, the default was reduced from 60000 to 32000 tokens to better balance cost and quality.

Output:

• If successful: A JSON object with `isError: false` and a `content` array containing a single text item. The `text` field holds the code review generated by the LLM in markdown format.
• If an error occurs: A JSON object with `isError: true` and a `content` array. The `text` field will contain an error message describing the issue.

Environment Variables

For the LLM integration to work, the `claude-code-review-mcp` server (the process started by `npx` or `claude-code-review-mcp`) needs access to the respective API keys.

Set these in your shell environment or place them in a `.env` file in the root directory of the project you are reviewing:

• For Google Models:

`GOOGLE_API_KEY="your_google_api_key"`

• For OpenAI Models:

`OPENAI_API_KEY="your_openai_api_key"`

• For Anthropic Models:

`ANTHROPIC_API_KEY="your_anthropic_api_key"`

The server will automatically load variables from a `.env` file found in the current working directory (i.e., your project's root) or you can configure them directly in the MCP server configuration as shown in the examples above.

Smart Slash Commands for Claude Code

The package includes several improved slash commands in the `examples/claude-commands/` directory that you can copy to your project's `.claude/commands/` directory. These commands take advantage of Claude Code's understanding of your project context and current task, eliminating the need for manual input.

Available Slash Commands

To use these commands:

1. Copy the desired command files from the `examples/claude-commands/` directory to your project's `.claude/commands/` directory

2. Invoke the command in Claude Code with `/project:command-name` (e.g., `/project:review-staged-claude`)

These commands automatically use Claude's knowledge of your current task and project context, eliminating the need for lengthy manual arguments.

Security Considerations

• API Key Handling: API keys for LLM providers are sensitive credentials. This tool accesses them from environment variables or `.env` files, but does not store or transmit them beyond the necessary API calls. Consider using a secure environment variable manager for production environments.

• Git Repository Analysis: The tool analyzes your local Git repository contents. It executes Git commands and reads diff output, but does not transmit your entire codebase to the LLM - only the specific changes being reviewed.

• Code Privacy: When sending code for review to external LLM providers, be mindful of:
  • Sensitive information in code comments or strings
  • Proprietary algorithms or trade secrets
  • Authentication credentials or API keys in config files

• Branch Name Sanitization: To prevent command injection, branch names are sanitized before being used in Git commands. However, it's still good practice to avoid using unusual characters in branch names.

Development (for the `@vibesnipe/code-review-mcp` package itself)

If you are contributing to or modifying the `@vibesnipe/code-review-mcp` package:

1. Clone the Monorepo:

Ensure you have the repo cloned.

2. Navigate to Package:

cd /path/to/claude-code-review-mcp

3. Install Dependencies:

pnpm install

4. Run in Development Mode:

This uses `tsx` for hot-reloading TypeScript changes.

pnpm dev

The server will start and log to `stderr`.

5. Testing with Claude Code (Local Development):

You'll need to tell Claude Code where your local development server script is:

# From any directory where you use Claude Code
    claude mcp add local-code-reviewer "node /path/to/claude-code-review-mcp/src/index.ts" --interpreter=tsx

Now, when Claude Code needs the "local-code-reviewer", it will execute your source `index.ts` using `tsx`. Remember to replace `/path/to/claude-code-review-mcp/` with the actual absolute path to your repo.

Building for Production/Publishing

From the package directory:

pnpm build

This compiles TypeScript to JavaScript in the `dist` directory. The `prepublishOnly` script in `package.json` ensures this command is run automatically before publishing the package to npm.

Troubleshooting

• "Current directory is not a git repository...": Ensure you are running `npx @vibesnipe/code-review-mcp` (or the global command) from the root directory of a valid Git project.
• "API key for ... is not configured": Make sure the relevant environment variable (e.g., `OPENAI_API_KEY`) is set in the shell where you launched the MCP server OR in a `.env` file in your project's root.
• "Failed to get git diff. Git error: ...": This indicates an issue with the `git diff` command.
• LLM API Errors: Errors from the LLM providers (e.g., rate limits, invalid model name, authentication issues) will be passed through. Check the error message for details from the specific LLM API.
• Claude Code MCP Issues: If Claude Code isn't finding or launching the server, double-check your `claude mcp add ...` command and ensure the command specified for the MCP server is correct and executable. Use `claude mcp list` to verify.
• Cursor MCP Server Issues: If Cursor doesn't recognize the MCP server, make sure it's properly added in the settings with the correct configuration.
• Windsurf Workflow Errors: If Windsurf workflows are not executing correctly, check that:

License

MIT License - Copyright (c) Praney Behl