MCP Claude Code

# 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](https://github.com/BurntSushi/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: ```bash 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: ```json { "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: ```bash # Using pip pip install mcp-claude-code # Using uv (recommended) uv pip install mcp-claude-code ``` Then use the automatic installer: ```bash claudecode --install --allow-path /path/allow ``` Or configure Claude Desktop manually: ```json { "mcpServers": { "claude-code": { "command": "claudecode", "args": ["--allow-path", "/path/allow"] } } } ``` ### Method 3: Development Installation For development or local modifications: ```bash # 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: ```json { "mcpServers": { "claude-code": { "command": "python", "args": ["-m", "mcp_claude_code.cli", "--allow-path", "/path/allow"] } } } ``` ## Configuration Options ### Basic Configuration The minimum required configuration: ```json { "mcpServers": { "claude-code": { "command": "claudecode", "args": ["--allow-path", "/path/allow"] } } } ``` ### Advanced Configuration Full configuration with all available options: ```json { "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 ```bash --agent-model "openai/gpt-4o" --agent-model "openai/gpt-4o-mini" --agent-api-key "your-openai-api-key" ``` #### Anthropic Models ```bash --agent-model "anthropic/claude-3-5-sonnet-20241022" --agent-api-key "your-anthropic-api-key" ``` #### Google Models (via OpenRouter) ```bash --agent-model "openrouter/google/gemini-2.0-flash-exp" --agent-api-key "your-openrouter-api-key" ``` #### Local/Custom Models ```bash --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](https://github.com/BurntSushi/ripgrep): ```bash # 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: ```json { "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: ```bash # 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: ```bash # Run with verbose output python -m mcp_claude_code.cli --allow-path /path/to/project --transport stdio ``` ## Development and Testing For development work: ```bash # 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