Claude Code Installation¶

Claude Code is Anthropic's terminal-based AI coding tool. One command registers Code Scalpel as an MCP server and makes all 23 tools available in every claude session — no config file editing required.

Quick Setup (Recommended)¶

If you already have Claude Code installed, this is all you need:

claude mcp add codescalpel uvx codescalpel mcp

That's it. Verify with:

claude mcp list
# codescalpel: uvx codescalpel mcp

Then launch Claude Code in your project:

cd /path/to/your/project
claude

All 23 Code Scalpel tools are immediately available.

Full Setup Guide¶

Prerequisites¶

• Claude Code installed (download here)
• Terminal access (bash, zsh, or similar)
• Internet connection (first run downloads codescalpel via uvx)

Step 1: Install Claude CLI¶

Claude CLI is the official command-line interface for using Claude in your terminal.

# Install via Homebrew
brew tap anthropics/claude
brew install claude-cli

# Verify installation
claude --version

# Install via pip
pip install claude-cli

# Verify installation
claude --version

# Clone repository
git clone https://github.com/anthropics/claude-cli.git
cd claude-cli

# Install
pip install -e .

# Verify installation
claude --version

Step 2: Register Code Scalpel with Claude Code¶

Use the claude mcp add command — this is the recommended approach:

claude mcp add codescalpel uvx codescalpel mcp

What this does: - Registers codescalpel as a named MCP server globally - Sets uvx codescalpel mcp as the launch command (auto-installs/updates) - No manual JSON editing required - Persists across all Claude Code sessions

Verify:

claude mcp list
# codescalpel: uvx codescalpel mcp

Step 3: Manual Configuration (Alternative)¶

If you prefer editing config files directly, or need project-scoped settings, configure Claude Code manually.

Note: The claude mcp add command in Step 2 is equivalent to the global config below — use whichever fits your workflow.

Claude CLI uses a configuration file to manage MCP servers.

Global Configuration (All Projects)¶

Create or edit ~/.config/claude/config.json:

mkdir -p ~/.config/claude
cat > ~/.config/claude/config.json << 'EOF'
{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"]
    }
  }
}
EOF

Project-Specific Configuration¶

For project-specific settings, create .claude/config.json in your project directory:

cd /path/to/your/project
mkdir -p .claude
cat > .claude/config.json << 'EOF'
{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "./.code-scalpel/license/license.jwt"
      }
    }
  }
}
EOF

Step 4: Verify MCP Server Connection¶

Test that Claude CLI can connect to Code Scalpel:

# List available MCP servers
claude mcp list

# Expected output:
# Available MCP servers:
#   - code-scalpel (configured)

Test server startup:

# Start Claude with MCP servers
claude

# You should see startup messages indicating Code Scalpel loaded

Step 5: Test Code Scalpel Tools¶

Once Claude CLI is running, test Code Scalpel integration:

Interactive Test¶

claude

In the Claude CLI prompt:

You: What Code Scalpel tools are available?

Claude: [Calls get_capabilities tool]
I can see Code Scalpel has 23 tools available including:
- analyze_code
- extract_code
- security_scan
- get_call_graph
...

Non-Interactive Test¶

# Analyze a file directly
claude "Use analyze_code to analyze src/main.py"

# Security scan
claude "Use security_scan to check app.py for vulnerabilities"

# Extract a function
claude "Use extract_code to extract the authenticate function from auth.py"

Using Claude CLI with Code Scalpel¶

Starting Claude CLI¶

# Start interactive session
claude

# Start with a specific prompt
claude "Analyze the security of my Flask app"

# Start in a specific directory
cd /path/to/project
claude

Common Workflows¶

# Start Claude in your project
cd /path/to/project
claude

You: Analyze the main.py file structure

Claude: [Uses analyze_code tool]
I'll analyze main.py for you...

claude

You: Run a security scan on all Python files

Claude: [Uses crawl_project + security_scan]
I'll scan your project for security issues...

claude

You: Extract the login function from auth.py and show me the code

Claude: [Uses extract_code]
Here's the extracted login function with its dependencies...

Advanced Configuration¶

With License (Pro/Enterprise)¶

If you have a Pro or Enterprise license:

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

With Custom Project Root¶

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

With Debug Logging¶

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

MCP Server Management¶

Claude CLI provides commands to manage MCP servers:

List Servers¶

# List all configured MCP servers
claude mcp list

# Output:
# Available MCP servers:
#   - code-scalpel (configured)
#   - other-server (configured)

Check Server Status¶

# Test server connection
claude mcp test code-scalpel

# Expected output:
# Testing MCP server: code-scalpel
# ✓ Server started successfully
# ✓ Tools discovered: 23

Server Logs¶

# Start Claude with verbose logging
claude --verbose

# Or set environment variable
export CLAUDE_DEBUG=1
claude

Look for Code Scalpel startup logs:

[MCP] Starting server: code-scalpel
[MCP] code-scalpel: License detected: Pro tier
[MCP] code-scalpel: Server ready with 23 tools

Troubleshooting¶

Issue: "MCP server not found"¶

Problem: Claude can't find Code Scalpel configuration.

Solutions:

1. Check config file location:

   # Global config
   cat ~/.config/claude/config.json
   
   # Project config
   cat .claude/config.json
   

2. Verify JSON syntax:

   python -m json.tool ~/.config/claude/config.json
   

3. Check file permissions:

   chmod 644 ~/.config/claude/config.json
   

Issue: "Code Scalpel not responding"¶

Problem: MCP server starts but doesn't respond to tool calls.

Solutions:

1. Test server directly:

   uvx codescalpel mcp
   # Should not exit immediately (stdio mode)
   

2. Check Python path:

   which python
   # Make sure it's the same Python where codescalpel is installed
   

3. Reinstall Code Scalpel:

   pip uninstall codescalpel
   pip install codescalpel
   

Issue: "License not detected"¶

Problem: Pro/Enterprise features not available.

Solutions:

1. Check license file exists:

   ls -lh ~/.config/code-scalpel/license.jwt
   

2. Verify LICENSE_PATH in config:

   {
     "mcpServers": {
       "code-scalpel": {
         "env": {
           "CODE_SCALPEL_LICENSE_PATH": "/full/path/to/license.jwt"
         }
       }
     }
   }
   

3. Test license directly:

   python -c "from code_scalpel.licensing.jwt_validator import get_current_tier; print(f'Tier: {get_current_tier()}')"
   

See License Activation Guide for complete troubleshooting.

Issue: "Tools not showing up"¶

Problem: Claude says it doesn't have access to Code Scalpel tools.

Solutions:

1. Restart Claude CLI:

   # Exit Claude (Ctrl+D or type exit)
   claude
   

2. Clear MCP cache:

   rm -rf ~/.cache/claude/mcp*
   claude
   

3. Check server startup in logs:

   claude --verbose
   

Look for:

[MCP] code-scalpel: Server ready with 23 tools

Issue: "Permission denied"¶

Problem: Can't execute Python or access files.

Solutions:

1. Check Python executable:

   which python
   python --version
   

2. Make config directory writable:

   chmod 755 ~/.config/claude
   

3. Use full uvx path:

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

Tips & Best Practices¶

1. Use Project-Specific Configs¶

For team projects, commit .claude/config.json to version control:

# .gitignore
!.claude/config.json  # Include Claude config
.code-scalpel/license/  # Exclude license files

2. Combine with Shell Aliases¶

# Add to ~/.bashrc or ~/.zshrc
alias cs='claude'
alias csa='claude "Analyze this codebase"'
alias css='claude "Run a security scan"'

3. Use Environment Variables¶

For CI/CD or temporary overrides:

# Temporary Pro license for testing
CODE_SCALPEL_LICENSE_PATH=/tmp/test-license.jwt claude

# Custom project root
CODE_SCALPEL_ROOT=/path/to/project claude

4. Script Claude CLI¶

Automate code analysis in scripts:

#!/bin/bash
# analyze-pr.sh - Analyze changed files in a PR

CHANGED_FILES=$(git diff --name-only main...HEAD | grep '\.py$')

for file in $CHANGED_FILES; do
  echo "Analyzing $file..."
  claude "Use analyze_code and security_scan on $file. Summarize any issues."
done

5. Integrate with Git Hooks¶

Pre-commit hook example:

#!/bin/bash
# .git/hooks/pre-commit

STAGED_PY_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.py$')

if [ -n "$STAGED_PY_FILES" ]; then
  echo "Running Code Scalpel security scan..."
  for file in $STAGED_PY_FILES; do
    claude "Use security_scan on $file. Report any critical issues." || exit 1
  done
fi

Next Steps¶

• ✅ License Activation - Activate Pro/Enterprise tiers
• ✅ First Analysis - Run your first code analysis
• ✅ Tool Reference - Explore all 23 tools
• ✅ Configuration Guide - Advanced settings

Getting Help¶

• 📧 Email: support@codescalpel.dev
• 💬 Discord: discord.gg/codescalpel
• 📚 Docs: codescalpel.dev/docs
• 🐛 Issues: github.com/code-scalpel/code-scalpel/issues

Ready to analyze code from your terminal? Start Claude CLI and ask it to analyze your first file! 🚀