@codesherlock/codesherlock-local-mcp-server

CodeSherlock MCP Server - Setup & Usage Guide

⚠️ Beta Version Notice
This is a beta release of the CodeSherlock MCP Server. Features may change, and some functionality may be experimental. We welcome your feedback to help us improve!

Key Features:

• Analyze uncommitted changes (staged and unstaged files)
• Analyze committed changes (from your latest commit)
• Perform security analysis using OWASP Top 10 and CWE frameworks
• Integration with AI assistants like Claude Desktop, Cline, and other MCP-compatible tools

Prerequisites

Before you begin, ensure you have:

• Node.js (version 18.0.0 or higher) and npm installed on your system
• A Git repository with code you want to analyze
• An AI coding assistant that supports MCP (e.g., Claude Code, Cursor, VS Code, Cline, or similar)

The CodeSherlock MCP Server is available on the npm registry and can be used directly with npx.

Step 1: Get Your API Key

CodeSherlock requires an API key to analyze your code. This API Key is used to authenticate your requests to the CodeSherlock API.

Obtaining Your API Key

• Visit the CodeSherlock API Key page: https://codesherlock.ai/mcp-api-key
• Sign in or create an account if you haven't already
• Generate a new API key
• Copy and store your API key securely - you'll need to provide it when prompted

Important Security Notes

• Never share your API key with others
• Never commit your API key to version control
• Store it in a secure location (password manager recommended)
• If your key is compromised, regenerate it immediately from the CodeSherlock dashboard

Step 2: Configure Your AI Assistant

You need to add the CodeSherlock MCP Server configuration to your AI assistant's settings. Follow the instructions for your preferred IDE/assistant below.

Quick Links:

• Cursor
• Windsurf
• Claude Code
• VS Code
• IntelliJ IDEA
• Cline

Cursor

Steps to Configure

• Click the Settings (gear icon) on the top right corner
• Settings panel opens as a new tab in the center of the screen
• In the settings sidebar, navigate to Tools & MCP section
• Click on New MCP Server button
• This opens the mcp.json config file
• Add the configuration below and save
• Restart Cursor

Configuration

{
  "mcpServers": {
    "codesherlock": {
      "name": "CodeSherlock MCP Server (Beta)",
      "description": "CodeSherlock delivers deep code analysis and exposes MCP tools for commit analysis and uncommit analysis.",
      "command": "npx",
      "args": [
        "-y",
        "codesherlock-mcp-server"
      ],
      "env": {
        "MCP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Config File Location

OS	Path
Windows	C:\Users\<Username>\.cursor\mcp.json
macOS	~/.cursor/mcp.json

Windsurf

Steps to Configure

• Click on the Settings (gear icon) on the top right corner and select Windsurf Settings (or press Ctrl+,)
• In the settings search box, type mcp
• Find the MCP Servers section
• Click on Open MCP Marketplace
• In the MCP Marketplace, click the Settings (gear icon) to add a custom server
• This opens the mcp_config.json config file
• Add the configuration below and save
• Restart Windsurf

Configuration

{
  "mcpServers": {
    "codesherlock": {
      "name": "CodeSherlock MCP Server (Beta)",
      "description": "CodeSherlock delivers deep code analysis and exposes MCP tools for commit analysis and uncommit analysis.",
      "command": "npx",
      "args": [
        "-y",
        "codesherlock-mcp-server"
      ],
      "env": {
        "MCP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Config File Location

OS	Path
Windows	C:\Users\<Username>\.codeium\windsurf\mcp_config.json
macOS	~/.codeium/windsurf/mcp_config.json

Claude Code

Steps to Configure

Run the following command in your terminal:

claude mcp add codesherlock -e MCP_API_KEY=your-api-key-here -- npx -y codesherlock-mcp-server

Other useful commands:

claude mcp list                  # List all configured servers
claude mcp remove codesherlock   # Remove a server

Configuration

Manually add to config file (optional):

{
  "mcpServers": {
    "codesherlock": {
      "command": "npx",
      "args": [
        "-y",
        "codesherlock-mcp-server"
      ],
      "env": {
        "MCP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Config File Location

OS	Path
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/.claude/claude_desktop_config.json

VS Code

Steps to Configure

• Press Ctrl+Shift+P (Windows) or Cmd+Shift+P (macOS) to open Command Palette
• Type MCP: Open User Configuration
• This opens the mcp.json config file
• Add the configuration below and save
• Restart VS Code

Configuration

{
  "mcpServers": {
    "codesherlock": {
      "name": "CodeSherlock MCP Server (Beta)",
      "description": "CodeSherlock delivers deep code analysis and exposes MCP tools for commit analysis and uncommit analysis.",
      "command": "npx",
      "args": [
        "-y",
        "codesherlock-mcp-server"
      ],
      "env": {
        "MCP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Config File Location

OS	Path
Windows	C:\Users\<Username>\AppData\Roaming\Code\User\mcp.json
macOS	~/Library/Application Support/Code/User/mcp.json

IntelliJ IDEA

Steps to Configure

Method 1: Using JetBrains AI Assistant

Requires JetBrains AI Assistant plugin installed

• Click on the Settings (gear icon)
• Navigate to Tools → AI Assistant → MCP
• Add the configuration below and save
• Restart IntelliJ IDEA

Method 2: Using GitHub Copilot

Requires GitHub Copilot plugin installed

• Click on the Settings (gear icon)
• Navigate to Tools → GitHub Copilot → MCP
• Add the configuration below and save
• Restart IntelliJ IDEA

Configuration

For JetBrains AI Assistant:

{
  "mcpServers": {
    "codesherlock": {
      "name": "CodeSherlock MCP Server (Beta)",
      "description": "CodeSherlock delivers deep code analysis and exposes MCP tools for commit analysis and uncommit analysis.",
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": [
        "-y",
        "codesherlock-mcp-server"
      ],
      "env": {
        "MCP_API_KEY": "your-api-key-here"
      }
    }
  }
}

For GitHub Copilot:

{
  "servers": {
    "codesherlock": {
      "name": "CodeSherlock MCP Server (Beta)",
      "description": "CodeSherlock delivers deep code analysis and exposes MCP tools for commit analysis and uncommit analysis.",
      "command": "npx",
      "args": [
        "-y",
        "codesherlock-mcp-server"
      ],
      "env": {
        "MCP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Config File Location

GitHub Copilot:

OS	Path
Windows	C:\Users\<Username>\AppData\Local\github-copilot\intellij\mcp.json
macOS	~/Library/Application Support/github-copilot/intellij/mcp.json

Cline

Cline is a VS Code extension. Install it from the VS Code marketplace or other supported IDEs.

Steps to Configure

• Open Cline panel in VS Code
• Click on Manage MCP Servers
• Click on the Settings (gear icon)
• Click on Configure MCP Servers button
• This opens the cline_mcp_settings.json config file
• Add the configuration below and save
• Restart VS Code

Configuration

{
  "mcpServers": {
    "codesherlock": {
      "name": "CodeSherlock MCP Server (Beta)",
      "description": "CodeSherlock delivers deep code analysis and exposes MCP tools for commit analysis and uncommit analysis.",
      "command": "npx",
      "args": [
        "-y",
        "codesherlock-mcp-server"
      ],
      "env": {
        "MCP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Config File Location

OS	Path
Windows	C:\Users\<Username>\AppData\Roaming\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
macOS	~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Step 3: Using CodeSherlock with Your AI Assistant

Once configured, you can start using CodeSherlock by prompting your AI assistant. The assistant will automatically invoke the MCP server tools to perform code analysis.

Analysis Types

CodeSherlock supports three analysis factors:

Factor	Description
power analysis	A full-spectrum scan that covers the most essential and critical issues
owasp	Security analysis based on OWASP Top 10 vulnerabilities
cwe	Analyzes code against Common Weakness Enumeration (CWE) framework

Example Prompts

Here are practical examples of how to prompt your AI assistant to perform code analysis:

"Review my uncommitted changes using CodeSherlock"

"Use CodeSherlock to check my uncommitted code for CWE vulnerabilities"

"Analyze my latest commit for OWASP vulnerabilities using CodeSherlock"

"Check the last commit in my current repo for CWE issues with CodeSherlock"

Understanding the Results

When Analysis Completes

The AI assistant will present the analysis results in a readable format, typically including:

• Number of issues found
• Severity levels (Critical, High, Medium, Low)
• Issue categories
• Affected files and line numbers
• Descriptions and recommendations for each issue

Troubleshooting

Common Issues

"Server not found" or "MCP server failed to start"

Solution:

• Verify the configuration file path is correct
• Check that Node.js and npm are properly installed

"Authentication failed" or "Invalid API key"

Solution:

• Verify your API key is correctly added to the configuration
• Check for any extra spaces or characters in the API key
• Regenerate your API key from the CodeSherlock dashboard
• Ensure you've restarted your AI assistant after adding the key

"Not a Git repository"

Solution:

• Ensure you're analyzing a directory that contains a .git folder
• Initialize a Git repository if needed: git init

"No changes to analyze"

Solution:

• For uncommitted analysis: Make sure you have modified files
• For commit analysis: Verify the commit exists using git log
• Check that you're in the correct Git repository

Analysis takes too long or times out

Solution:

• Start with analyzing specific files or smaller changesets
• Check your internet connection
• Break large changes into smaller commits for analysis

Best Practices

1. Integrate into Your Workflow

• Before committing: Analyze uncommitted changes to catch issues early
• After committing: Review commits before pushing to remote
• During code review: Use analysis results to supplement manual reviews

2. Choose the Right Analysis Factor

• Use OWASP Best for web applications and APIs; focuses on the OWASP Top 10 and other common web security risks.
• Use CWE Ideal when you need deeper, classification-based coverage of software weaknesses across all domains.
• Use Power Analysis A broad, high-coverage analysis designed to catch the most essential and critical issues across any type of project (web, mobile, backend, etc.)

3. Act on Results

• Prioritize Critical and High severity issues immediately
• Create tickets for Medium severity issues
• Document Low severity issues for future refactoring

Beta Version Feedback

As this is a beta release, we're actively seeking feedback to improve the CodeSherlock MCP Server. If you encounter any issues, have suggestions, or want to report bugs, please:

• Send us an email at [e-mail]
• Include details about your environment, the issue you encountered, and any error messages

Your feedback helps us make CodeSherlock better for everyone!

Getting Help

If you face any issues, please send us a mail at [e-mail]. We will help you resolve the issue as soon as possible.