Skip to main content

🤖 Claude Desktop Installation

Step-by-step guide to installing Code Scalpel for Claude Desktop on macOS, Windows, and Linux.

Prerequisites

Before you begin, ensure you have:

  • Claude Desktop installed (download here)
  • Python 3.10+ installed
  • uv or pip package manager

💡 Check Python Version

python --version
# Should show Python 3.10 or higher

1Install Code Scalpel

Choose your preferred installation method:

The fastest option—no global installation needed:

# Verify uv is installed
uv --version

# Test Code Scalpel runs
uvx codescalpel --version

Installing uv

If you don't have uv, install it:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Traditional Python package installation:

pip install codescalpel

# Verify installation
codescalpel --version

Installs in an isolated environment:

pipx install codescalpel
codescalpel --version

2Locate Claude Desktop Config

Claude Desktop stores its configuration in a JSON file. The location depends on your operating system:

# Config file location
~/Library/Application Support/Claude/claude_desktop_config.json

# Open in default editor
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Or create if it doesn't exist
mkdir -p ~/Library/Application\ Support/Claude
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
# Config file location
%APPDATA%\Claude\claude_desktop_config.json

# Open in Notepad
notepad %APPDATA%\Claude\claude_desktop_config.json

# Or create if it doesn't exist
mkdir %APPDATA%\Claude 2>nul
echo {} > %APPDATA%\Claude\claude_desktop_config.json
# Config file location
~/.config/Claude/claude_desktop_config.json

# Open in editor
nano ~/.config/Claude/claude_desktop_config.json

# Or create if it doesn't exist
mkdir -p ~/.config/Claude
echo '{}' > ~/.config/Claude/claude_desktop_config.json

3Add Code Scalpel Configuration

Edit the config file to add Code Scalpel as an MCP server:

{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"]
    }
  }
}

First, find your Python path:

which python  # macOS/Linux
where python  # Windows

Then use the full path in config:

{
  "mcpServers": {
    "code-scalpel": {
      "command": "/usr/local/bin/python",
      "args": ["-m", "code_scalpel"]
    }
  }
}

⚠️ Use Absolute Paths

Always use the full absolute path to Python when using pip installation. Relative paths or python alone may not work reliably.

If you need to set environment variables (e.g., for Pro/Enterprise license):

{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "/path/to/license.jwt"
      }
    }
  }
}

4Restart Claude Desktop

After saving the configuration file:

  1. Quit Claude Desktop completely (not just close the window)
    • macOS: Cmd+Q or Claude → Quit Claude
    • Windows: Right-click tray icon → Exit
    • Linux: Close all windows and check system tray
  2. Reopen Claude Desktop
  3. Verify the connection by looking for the MCP server indicator in Claude's interface

5Test the Installation

Start a new conversation with Claude and try:

Test Prompt

"What Code Scalpel tools do you have available?"

Claude should respond listing the available tools like analyze_code, extract_code, security_scan, etc.

Try a simple analysis:

Analysis Test

"Use Code Scalpel's analyze_code tool to analyze this Python code:

def greet(name: str) -> str:
    return f'Hello, {name}!'

You should see Claude invoke the analyze_code tool and return structured information about the function.

Configuration Options

Working Directory

To set a default working directory for file operations:

{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

Multiple Servers

You can run Code Scalpel alongside other MCP servers:

{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    }
  }
}

Pro/Enterprise License

To activate Pro or Enterprise features:

{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "/path/to/your/license.jwt"
      }
    }
  }
}

Troubleshooting

▶ Claude doesn't show Code Scalpel tools
  1. Verify config file syntax: Use a JSON validator to check for errors
  2. Check file location: Ensure the config file is in the correct directory
  3. Full restart: Quit Claude Desktop completely and reopen
  4. Check logs: Look at Claude Desktop's developer console for errors
▶ 'uvx' command not found

Install uv first:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Then restart your terminal and try again.

▶ Permission denied errors
  1. Check that the Python/uvx executable has execute permissions
  2. On macOS, you may need to allow the application in System Preferences → Security
  3. Try running the command manually in a terminal to see the full error
▶ Tools work but file paths fail
  1. Use absolute paths when referencing files
  2. Set the cwd option in your config to your project directory
  3. Check that Claude Desktop has permission to access the directories

Next Steps

🚀 What's Next