npm package: @suitable-adventures/checkmarx-mcp-server
Description: MCP server for Checkmarx SAST scanning - enables Claude to read security findings
Author: suitable-adventures
Latest version: 0.2.1

# Checkmarx MCP Server (Read-Only)

A Model Context Protocol (MCP) server that provides read-only access to Checkmarx SAST findings. This server enables AI assistants like Claude to retrieve and analyze security vulnerabilities from a pre-configured Checkmarx project.

## What's New in v0.2.0

- 🎯 **Severity-based sorting**: Findings are now automatically sorted by severity (HIGH → MEDIUM → LOW)
- 🔍 **New detail tool**: Get comprehensive details about specific findings including data flow analysis
- 🔧 **Fixed authentication**: Properly handles EU region authentication (eu.iam.checkmarx.net)
- 📊 **Improved error handling**: Better debugging and error messages

## Features

- **Read-Only Access**: View SAST vulnerability findings from your Checkmarx project
- **Latest Scan Results**: Automatically retrieves findings from the most recent completed scan
- **Severity Breakdown**: See vulnerabilities categorized by severity (High/Medium/Low)
- **Detailed Findings**: Access vulnerability names, file locations, and line numbers

## Prerequisites

- Node.js 18+ installed
- Checkmarx One account with API access
- A Checkmarx project ID with existing scans
- API key with read permissions

## Installation

### Option 1: Using Claude MCP Add (Recommended)

Install directly using Claude's MCP command:

```bash
claude mcp add checkmarx \
  --env CHECKMARX_API_KEY=YOUR_API_KEY \
  --env CHECKMARX_BASE_URL=https://ast.checkmarx.net \
  --env CHECKMARX_TENANT=YOUR_TENANT \
  --env CHECKMARX_PROJECT_ID=YOUR_PROJECT_ID \
  -- npx -y @suitable-adventures/checkmarx-mcp-server
```

Replace the environment variable values with your actual Checkmarx credentials.

### Option 2: Manual Installation

1. Install globally via npm:
```bash
npm install -g @suitable-adventures/checkmarx-mcp-server
```

2. Or clone this repository:
```bash
git clone https://github.com/suitable-adventures/checkmarx-mcp.git
cd checkmarx-mcp
npm install
npm run build
```

## Configuration for Claude Desktop (Manual Setup)

If you installed manually, add the server to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

For globally installed package:
```json
{
  "mcpServers": {
    "checkmarx-findings": {
      "command": "npx",
      "args": ["-y", "@suitable-adventures/checkmarx-mcp-server"],
      "env": {
        "CHECKMARX_API_KEY": "your_api_key_here",
        "CHECKMARX_BASE_URL": "https://ast.checkmarx.net",
        "CHECKMARX_TENANT": "your_tenant",
        "CHECKMARX_PROJECT_ID": "your_project_id"
      }
    }
  }
}
```

For local installation:
```json
{
  "mcpServers": {
    "checkmarx-findings": {
      "command": "node",
      "args": ["/path/to/checkmarx-mcp/build/index.js"],
      "env": {
        "CHECKMARX_API_KEY": "your_api_key_here",
        "CHECKMARX_BASE_URL": "https://ast.checkmarx.net",
        "CHECKMARX_TENANT": "your_tenant",
        "CHECKMARX_PROJECT_ID": "your_project_id"
      }
    }
  }
}
```

## Available Tools

### `checkmarx_list_findings`
Lists SAST vulnerability findings from the latest scan of the configured project, sorted by severity (HIGH → MEDIUM → LOW).
- `limit` (optional): Maximum number of findings to return (default: 100)

Returns:
- Total vulnerability count
- Severity breakdown (High/Medium/Low)
- Top findings with file locations and line numbers, prioritized by severity

### `checkmarx_get_finding_details`
Gets comprehensive details about a specific finding.
- `resultId` (required): The ID of the finding to get details for

Returns:
- Complete vulnerability information including severity, status, and state
- Data flow path showing how tainted data moves through the code
- CWE details and compliance standards violated
- File location with line and column numbers
- Scan context including when first found

## Usage Examples

After configuring the server in Claude Desktop, you can use commands like:

**Listing findings:**
- "Show me the latest Checkmarx findings"
- "List the top 5 security vulnerabilities"
- "What are the high severity issues in my project?"
- "Show me 10 SAST findings"

**Getting details:**
- "Get details for finding ID xyz123"
- "Show me the data flow for this vulnerability"
- "Explain how this security issue works"

## How It Works

1. The server connects to Checkmarx using your API credentials
2. It automatically finds the latest completed scan for your configured project
3. Retrieves the vulnerability findings from that scan
4. Presents them in a readable format with severity categorization

## Development

- `npm run build`: Compile TypeScript
- `npm run watch`: Watch mode for development
- `npm run inspector`: Test with MCP Inspector

## API Endpoints Used

This server interacts with the following Checkmarx One API endpoints:
- `/auth/realms/{tenant}/protocol/openid-connect/token` - Authentication
- `/api/scans` - Get latest scan for project
- `/api/scan-results` - Retrieve vulnerability results

## Security Notes

- This is a read-only server - it cannot create projects or initiate scans
- API keys are stored in environment variables
- Never commit `.env` files to version control
- Ensure your API key has appropriate read permissions

## Troubleshooting

1. **No scans found**: Verify the project ID is correct and has completed scans
2. **Authentication Errors**: Check your API key and tenant configuration
3. **Connection Issues**: Verify the base URL matches your Checkmarx region
4. **Empty results**: Ensure the latest scan has completed successfully

## License

MIT