Installation Guide

This guide covers different installation methods for mcp-claude-code and how to configure it with Claude Desktop.

Requirements

• Python 3.12 or later
• Claude Desktop application
• Optional: ripgrep for enhanced search performance

Installation Methods

Method 1: Using uvx (Recommended)

The simplest way to use mcp-claude-code is with uvx, which runs the package without permanent installation:

uvx --from mcp-claude-code claudecode --install

I highly recommend that you set projects one by one to gain more efficient system prompt generation experience.

This command will automatically configure Claude Desktop for you.

For manual configuration:

{
  "mcpServers": {
    "claude-code": {
      "command": "uvx",
      "args": [
        "--from",
        "mcp-claude-code",
        "claudecode",
        "--allow-path",
        "/path/allow",
        "--project",
        "/path/project1",
        "--project",
        "/path/project2"
      ]
    }
  }
}

Method 2: Using pip/uv

Install the package globally or in a virtual environment:

# Using pip
pip install mcp-claude-code

# Using uv (recommended)
uv pip install mcp-claude-code

Then use the automatic installer:

claudecode --install --allow-path /path/allow

Or configure Claude Desktop manually:

{
  "mcpServers": {
    "claude-code": {
      "command": "claudecode",
      "args": ["--allow-path", "/path/allow"]
    }
  }
}

Method 3: Development Installation

For development or local modifications:

# Clone the repository
git clone https://github.com/SDGLBL/mcp-claude-code.git
cd mcp-claude-code

# Create virtual environment and install
make venv
make install-dev

# Activate virtual environment
source .venv/bin/activate  # On macOS/Linux
# .venv\Scripts\activate    # On Windows

# Use the installer
claudecode --install --allow-path /path/allow

Or use Python module syntax:

{
  "mcpServers": {
    "claude-code": {
      "command": "python",
      "args": ["-m", "mcp_claude_code.cli", "--allow-path", "/path/allow"]
    }
  }
}

Configuration Options

Basic Configuration

The minimum required configuration:

{
  "mcpServers": {
    "claude-code": {
      "command": "claudecode",
      "args": ["--allow-path", "/path/allow"]
    }
  }
}

Advanced Configuration

Full configuration with all available options:

{
  "mcpServers": {
    "claude-code": {
      "command": "claudecode",
      "args": [
        "--allow-path",
        "/path/to/project1",
        "--allow-path",
        "/path/to/project2",
        "--project",
        "/path/to/project1",
        "--project",
        "/path/to/project2",
        "--name",
        "custom-claude-code",
        "--transport",
        "stdio",
        "--command-timeout",
        "180",
        "--enable-agent-tool",
        "--agent-model",
        "openai/gpt-4o",
        "--agent-max-tokens",
        "100000",
        "--agent-api-key",
        "your-api-key-here",
        "--agent-base-url",
        "http://localhost:1234/v1",
        "--agent-max-iterations",
        "10",
        "--agent-max-tool-uses",
        "30"
      ]
    }
  }
}

Configuration Parameters

Parameter	Type	Default	Description
--allow-path	string	current directory	Directory path to allow access (can be specified multiple times)
--project	string	-	Project path for prompt generation (can be specified multiple times Highly Recommend)
--name	string	"claude-code"	Name of the MCP server
--transport	choice	"stdio"	Transport protocol ("stdio" or "sse")
--command-timeout	float	120.0	Default timeout for command execution in seconds
--enable-agent-tool	flag	false	Enable the agent tool functionality
--agent-model	string	-	Model name in LiteLLM format (e.g., "openai/gpt-4o")
--agent-max-tokens	integer	-	Maximum tokens for agent responses
--agent-api-key	string	-	API key for the LLM provider
--agent-base-url	string	-	Base URL for the LLM provider API endpoint
--agent-max-iterations	integer	10	Maximum number of iterations for agent
--agent-max-tool-uses	integer	30	Maximum number of total tool uses for agent

Project Paths vs Allow Paths

• --allow-path: Controls which directories the server can access for file operations
• --project: Generates project-specific prompts with git info, directory structure, and environment details

The --project argument enables automatic generation of comprehensive system prompts that include:

• Git repository information (current branch, recent commits, status)
• Directory structure overview
• Operating system details
• Project-specific context for better assistance

You can specify multiple projects to generate prompts for each one.

Agent Tool Configuration

The agent tool allows Claude to delegate tasks to specialized sub-agents. It's disabled by default and requires additional configuration.

Enabling Agent Tool

To enable the agent tool, you need:

1. Add --enable-agent-tool to your configuration
2. Configure an LLM provider with API key

Supported LLM Providers

The agent tool uses LiteLLM format for model specification:

OpenAI Models

--agent-model "openai/gpt-4o"
--agent-model "openai/gpt-4o-mini"
--agent-api-key "your-openai-api-key"

Anthropic Models

--agent-model "anthropic/claude-3-5-sonnet-20241022"
--agent-api-key "your-anthropic-api-key"

Google Models (via OpenRouter)

--agent-model "openrouter/google/gemini-2.0-flash-exp"
--agent-api-key "your-openrouter-api-key"

Local/Custom Models

--agent-model "openai/gpt-4o"  # or any compatible model name
--agent-base-url "http://localhost:1234/v1"
--agent-api-key "local-key"  # often not needed for local

Environment Variables

Instead of command-line arguments, you can use environment variables:

Environment Variable	Description
AGENT_MODEL	Default model name
AGENT_PROVIDER	Default provider prefix
AGENT_MAX_TOKENS	Maximum tokens for model responses
OPENAI_API_KEY	OpenAI API key
ANTHROPIC_API_KEY	Anthropic API key
AGENT_TEMPERATURE	Model temperature (default: 0.7)
AGENT_API_TIMEOUT	API timeout in seconds (default: 60)

Claude Desktop Configuration Locations

The configuration file locations vary by operating system:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

Performance Optimization

Install ripgrep

For faster file searches, install ripgrep:

# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

# Windows (using Chocolatey)
choco install ripgrep

# Or download from: https://github.com/BurntSushi/ripgrep/releases

Timeout Configuration

Adjust command timeout for large operations:

{
  "mcpServers": {
    "claude-code": {
      "command": "claudecode",
      "args": ["--command-timeout", "300", "--allow-path", "/path/to/project"]
    }
  }
}

Troubleshooting

Common Issues

1. Permission Errors: Ensure the specified paths in --allow-path exist and are accessible
2. Command Not Found: Make sure the installation method puts claudecode in your PATH
3. Agent Tool Not Working: Verify the API key and model name are correct
4. Claude Desktop Not Recognizing Server: Restart Claude Desktop after configuration changes

Verification

Test your installation:

# Check if the command works
claudecode --help

# Test with a simple allowed path
claudecode --allow-path /tmp

Debug Mode

For troubleshooting, you can run the server directly:

# Run with verbose output
python -m mcp_claude_code.cli --allow-path /path/to/project --transport stdio

Development and Testing

For development work:

# Install development dependencies
make install-dev

# Run tests
make test

# Run with coverage
make test-cov

# Lint code
make lint

# Format code
make format

Next Steps

After installation:

1. Restart Claude Desktop
2. Verify the server appears in Claude Desktop's MCP servers list
3. Test basic functionality by asking Claude to list files in your project