claude-code-action/docs/configuration.md

Advanced Configuration

Using Custom MCP Configuration

The mcp_config input allows you to add custom MCP (Model Context Protocol) servers to extend Claude's capabilities. These servers merge with the built-in GitHub MCP servers.

Basic Example: Adding a Sequential Thinking Server

- uses: anthropics/claude-code-action@beta
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    mcp_config: |
      {
        "mcpServers": {
          "sequential-thinking": {
            "command": "npx",
            "args": [
              "-y",
              "@modelcontextprotocol/server-sequential-thinking"
            ]
          }
        }
      }
    allowed_tools: "mcp__sequential-thinking__sequentialthinking" # Important: Each MCP tool from your server must be listed here, comma-separated
    # ... other inputs

Passing Secrets to MCP Servers

For MCP servers that require sensitive information like API keys or tokens, use GitHub Secrets in the environment variables:

- uses: anthropics/claude-code-action@beta
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    mcp_config: |
      {
        "mcpServers": {
          "custom-api-server": {
            "command": "npx",
            "args": ["-y", "@example/api-server"],
            "env": {
              "API_KEY": "${{ secrets.CUSTOM_API_KEY }}",
              "BASE_URL": "https://api.example.com"
            }
          }
        }
      }
    # ... other inputs

Using Python MCP Servers with uv

For Python-based MCP servers managed with uv, you need to specify the directory containing your server:

- uses: anthropics/claude-code-action@beta
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    mcp_config: |
      {
        "mcpServers": {
          "my-python-server": {
            "type": "stdio",
            "command": "uv",
            "args": [
              "--directory",
              "${{ github.workspace }}/path/to/server/",
              "run",
              "server_file.py"
            ]
          }
        }
      }
    allowed_tools: "my-python-server__<tool_name>" # Replace <tool_name> with your server's tool names
    # ... other inputs

For example, if your Python MCP server is at mcp_servers/weather.py, you would use:

"args":
  ["--directory", "${{ github.workspace }}/mcp_servers/", "run", "weather.py"]

Important:

• Always use GitHub Secrets (${{ secrets.SECRET_NAME }}) for sensitive values like API keys, tokens, or passwords. Never hardcode secrets directly in the workflow file.
• Your custom servers will override any built-in servers with the same name.

Additional Permissions for CI/CD Integration

The additional_permissions input allows Claude to access GitHub Actions workflow information when you grant the necessary permissions. This is particularly useful for analyzing CI/CD failures and debugging workflow issues.

Enabling GitHub Actions Access

To allow Claude to view workflow run results, job logs, and CI status:

1. Grant the necessary permission to your GitHub token:

   • When using the default GITHUB_TOKEN, add the actions: read permission to your workflow:

   permissions:
     contents: write
     pull-requests: write
     issues: write
     actions: read # Add this line
   

2. Configure the action with additional permissions:

   - uses: anthropics/claude-code-action@beta
     with:
       anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
       additional_permissions: |
         actions: read
       # ... other inputs
   

3. Claude will automatically get access to CI/CD tools: When you enable actions: read, Claude can use the following MCP tools:

   • mcp__github_ci__get_ci_status - View workflow run statuses
   • mcp__github_ci__get_workflow_run_details - Get detailed workflow information
   • mcp__github_ci__download_job_log - Download and analyze job logs

Example: Debugging Failed CI Runs

name: Claude CI Helper
on:
  issue_comment:
    types: [created]

permissions:
  contents: write
  pull-requests: write
  issues: write
  actions: read # Required for CI access

jobs:
  claude-ci-helper:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@beta
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          additional_permissions: |
            actions: read
          # Now Claude can respond to "@claude why did the CI fail?"

Important Notes:

• The GitHub token must have the actions: read permission in your workflow
• If the permission is missing, Claude will warn you and suggest adding it
• Currently, only actions: read is supported, but the format allows for future extensions

Custom Environment Variables

You can pass custom environment variables to Claude Code execution using the claude_env input. This is useful for CI/test setups that require specific environment variables:

- uses: anthropics/claude-code-action@beta
  with:
    claude_env: |
      NODE_ENV: test
      CI: true
      DATABASE_URL: postgres://test:test@localhost:5432/test_db
    # ... other inputs

The claude_env input accepts YAML format where each line defines a key-value pair. These environment variables will be available to Claude Code during execution, allowing it to run tests, build processes, or other commands that depend on specific environment configurations.

Limiting Conversation Turns

You can use the max_turns parameter to limit the number of back-and-forth exchanges Claude can have during task execution. This is useful for:

• Controlling costs by preventing runaway conversations
• Setting time boundaries for automated workflows
• Ensuring predictable behavior in CI/CD pipelines

- uses: anthropics/claude-code-action@beta
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    max_turns: "5" # Limit to 5 conversation turns
    # ... other inputs

When the turn limit is reached, Claude will stop execution gracefully. Choose a value that gives Claude enough turns to complete typical tasks while preventing excessive usage.

Custom Tools

By default, Claude only has access to:

• File operations (reading, committing, editing files, read-only git commands)
• Comment management (creating/updating comments)
• Basic GitHub operations

Claude does not have access to execute arbitrary Bash commands by default. If you want Claude to run specific commands (e.g., npm install, npm test), you must explicitly allow them using the allowed_tools configuration:

Note: If your repository has a .mcp.json file in the root directory, Claude will automatically detect and use the MCP server tools defined there. However, these tools still need to be explicitly allowed via the allowed_tools configuration.

- uses: anthropics/claude-code-action@beta
  with:
    allowed_tools: |
      Bash(npm install)
      Bash(npm run test)
      Edit
      Replace
      NotebookEditCell
    disallowed_tools: |
      TaskOutput
      KillTask
    # ... other inputs

Note: The base GitHub tools are always included. Use allowed_tools to add additional tools (including specific Bash commands), and disallowed_tools to prevent specific tools from being used.

Custom Model

Use a specific Claude model:

- uses: anthropics/claude-code-action@beta
  with:
    # model: "claude-3-5-sonnet-20241022"  # Optional: specify a different model
    # ... other inputs

Claude Code Settings

You can provide Claude Code settings to customize behavior such as model selection, environment variables, permissions, and hooks. Settings can be provided either as a JSON string or a path to a settings file.

Option 1: Settings File

- uses: anthropics/claude-code-action@beta
  with:
    settings: "path/to/settings.json"
    # ... other inputs

Option 2: Inline Settings

- uses: anthropics/claude-code-action@beta
  with:
    settings: |
      {
        "model": "claude-opus-4-1-20250805",
        "env": {
          "DEBUG": "true",
          "API_URL": "https://api.example.com"
        },
        "permissions": {
          "allow": ["Bash", "Read"],
          "deny": ["WebFetch"]
        },
        "hooks": {
          "PreToolUse": [{
            "matcher": "Bash",
            "hooks": [{
              "type": "command",
              "command": "echo Running bash command..."
            }]
          }]
        }
      }
    # ... other inputs

The settings support all Claude Code settings options including:

• model: Override the default model
• env: Environment variables for the session
• permissions: Tool usage permissions
• hooks: Pre/post tool execution hooks
• And more...

For a complete list of available settings and their descriptions, see the Claude Code settings documentation.

Notes:

• The enableAllProjectMcpServers setting is always set to true by this action to ensure MCP servers work correctly.
• If both the model input parameter and a model in settings are provided, the model input parameter takes precedence.
• The allowed_tools and disallowed_tools input parameters take precedence over permissions in settings.
• In a future version, we may deprecate individual input parameters in favor of using the settings file for all configuration.