kusari-inspector-mcp 0.2.4
MCP server for Kusari security scanning - integrates with Claude Code and other MCP clients
Requires Python: >=3.10
Keywords: mcp, security, scanning, kusari, claude-code, sast, vulnerability

# Kusari Inspector MCP Server

[![PyPI version](https://badge.fury.io/py/kusari-inspector-mcp.svg)](https://pypi.org/project/kusari-inspector-mcp/)
[![Python Support](https://img.shields.io/pypi/pyversions/kusari-inspector-mcp.svg)](https://pypi.org/project/kusari-inspector-mcp/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

An MCP (Model Context Protocol) server that integrates [Kusari](https://kusari.cloud) security scanning with Claude Code and other MCP-compatible AI assistants.

## What is This?

This MCP server lets AI assistants like Claude Code scan your code for security vulnerabilities, secrets, and other issues - directly from your IDE. It provides:

- **Vulnerability Detection**: Finds known security vulnerabilities in your dependencies
- **Secret Scanning**: Detects exposed credentials, API keys, and tokens
- **SAST Analysis**: Identifies security issues in your source code
- **SBOM Generation**: Creates software bill of materials
- **License Compliance**: Checks for license issues

All scans run securely in AWS Lambda using your Kusari account.

## Quick Start

### Installation

**Option 1: Using pip (recommended)**

```bash
pip install kusari-inspector-mcp
kusari-inspector-mcp install claude
```

**Option 2: Using uvx (no permanent install)**

```bash
# Install for Claude Code
uvx kusari-inspector-mcp install claude

# Or for other clients
uvx kusari-inspector-mcp install cursor
uvx kusari-inspector-mcp install windsurf
```

The setup wizard will automatically:
1. Configure the MCP server with your chosen client
2. Guide you through authentication on first use
3. Verify the installation

**Supported clients:** `claude`, `cursor`, `windsurf`, `cline`, `vscode`, `continue`, `copilot`, `antigravity`

List all clients:
```bash
kusari-inspector-mcp list
```

### Usage

Once installed, simply ask Claude Code to scan your code:

```
Claude, scan my local changes for security issues
```

or

```
Claude, run a full security audit on this repository
```

## Requirements

- Python 3.10 or higher
- Claude Code (VS Code extension) or another MCP-compatible client
- A Kusari account (free signup at [console.kusari.cloud](https://console.kusari.cloud))

## Manual Configuration

If the automatic setup doesn't work, you can configure manually.

**Note:** For backward compatibility, `kusari-inspector-setup` still works and defaults to Claude Code:
```bash
kusari-inspector-setup  # Same as: kusari-inspector-mcp install claude
```

### Using Claude CLI

```bash
claude mcp add --transport stdio kusari-inspector -- \
  python -m kusari_inspector_mcp.server
```

### Manual Config File Edit

Edit your Claude config file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: `~/.config/claude/claude_desktop_config.json`

Add this to the `mcpServers` section:

```json
{
  "mcpServers": {
    "kusari-inspector": {
      "command": "python",
      "args": ["-m", "kusari_inspector_mcp.server"],
      "env": {
        "CONSOLE_URL": "https://console.us.kusari.cloud/",
        "API_ENDPOINT": "https://platform.api.us.kusari.cloud/"
      }
    }
  }
}
```

Then reload VS Code.

## Authentication

On first use, the server will automatically:
1. Open your browser to authenticate with Kusari
2. Save your credentials securely to `~/.kusari/tokens.json`
3. Reuse the token for future scans

No additional configuration needed!

## Features

### Scan Local Changes
Fast diff-based scanning of uncommitted changes:
- Scans only modified files
- Detects new vulnerabilities in changed dependencies
- Finds secrets in code changes
- Results in ~30 seconds

### Full Repository Scan
Comprehensive security audit:
- OpenSSF Scorecard analysis
- Complete dependency tree scanning
- Full SAST analysis across all files
- Takes 3-10 minutes depending on repo size

### Web Console
Every scan includes a clickable link to view detailed results in the Kusari Cloud console with:
- Code context for each finding
- Remediation guidance
- Severity scoring
- Historical tracking

## Architecture

This MCP server wraps the official [Kusari CLI](https://github.com/kusaridev/kusari-cli), ensuring:
- **Consistent behavior** across CLI and MCP interfaces
- **Automatic updates** when the CLI improves
- **Secure execution** - all scans run in isolated AWS Lambda environments

```
Claude Code (VS Code)
    ↓
MCP Server (this package)
    ↓
Kusari CLI (auto-installed)
    ↓
    ├─ OAuth2 Authentication
    └─ AWS Lambda Scanning
```

## Configuration

### Environment Variables

You can customize the server using environment variables:

```bash
export CONSOLE_URL="https://console.us.kusari.cloud/"
export API_ENDPOINT="https://platform.api.us.kusari.cloud/"
export AUTH_ENDPOINT="https://auth.us.kusari.cloud/"
export VERBOSE="false"
```

### Config File

Or create `~/.kusari/mcp-config.yaml`:

```yaml
console_url: "https://console.us.kusari.cloud/"
api_endpoint: "https://platform.api.us.kusari.cloud/"
auth_endpoint: "https://auth.us.kusari.cloud/"
verbose: false
```

## Troubleshooting

### MCP Server Not Showing Up

```bash
# Verify installation
claude mcp list

# Should show: kusari-inspector - ✓ Connected
```

If not listed, try:
1. Reload VS Code: `Cmd+Shift+P` → "Developer: Reload Window"
2. Check the Output panel: `View` → `Output` → Select "Claude Code"
3. Re-run setup: `kusari-inspector-setup`

### Authentication Issues

```bash
# Check if authenticated
ls ~/.kusari/tokens.json

# Force re-authentication
rm ~/.kusari/tokens.json
# Then run a scan - it will prompt for auth
```

### CLI Installation Issues

The Kusari CLI is auto-installed to `~/.kusari/bin/kusari`. To verify:

```bash
~/.kusari/bin/kusari --version
```

To force a reinstall:

```bash
python -c "from kusari_inspector_mcp.cli_installer import KusariCLIInstaller; KusariCLIInstaller().ensure_installed(check_updates=True)"
```

## Development

### Installing from Test PyPI

To test pre-release versions published to test.pypi.org using uvx:

```bash
# Install for Claude Code from test.pypi.org (recommended method)
uvx --extra-index-url https://test.pypi.org/simple \
    --index-strategy unsafe-best-match \
    kusari-inspector-mcp@0.2.4 install claude

# Alternative: use --index (makes test.pypi primary for ALL packages)
uvx --index https://test.pypi.org/simple \
    --index-strategy unsafe-best-match \
    kusari-inspector-mcp@0.2.4 install claude

# Install for other clients
uvx --extra-index-url https://test.pypi.org/simple \
    --index-strategy unsafe-best-match \
    kusari-inspector-mcp@0.2.4 install cursor

# List all supported clients
uvx --extra-index-url https://test.pypi.org/simple \
    --index-strategy unsafe-best-match \
    kusari-inspector-mcp@0.2.4 list
```

**CLI commands:**
- `install <client>`: Install for a specific MCP client
- `uninstall <client>`: Uninstall from a specific client
- `list`: Show all supported clients

### Local Development

```bash
# Clone the repository
git clone https://github.com/kusaridev/kusari-inspector-mcp
cd kusari-inspector-mcp

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install in development mode (editable)
pip install -e .

# Add to Claude Code for local testing
# Replace /path/to/kusari-inspector-mcp with your actual path
claude mcp add kusari-inspector /path/to/kusari-inspector-mcp/venv/bin/kusari-inspector-mcp

# Example:
# claude mcp add kusari-inspector /Users/parth/Documents/pxp928/iac/.claude/mcp-servers/kusari-inspector/venv/bin/kusari-inspector-mcp

# Run tests (if you install dev dependencies)
pip install -e ".[dev]"
pytest

# Run the server directly for testing
python -m kusari_inspector_mcp.server
```

Any changes you make to the code in `kusari_inspector_mcp/` will be immediately reflected without needing to reinstall, since it's installed in editable mode.

### Building

```bash
# Build distribution
python -m build

# Install locally
pip install dist/kusari_inspector_mcp-*.whl

# Test installation
kusari-inspector-setup
```


## CLI Reference

```bash
# Install for specific client
kusari-inspector-mcp install <client>

# Uninstall from specific client
kusari-inspector-mcp uninstall <client>

# List all supported clients
kusari-inspector-mcp list

# Get help
kusari-inspector-mcp --help
```

**Available clients:**
- `claude` - Claude Code (VS Code extension)
- `cursor` - Cursor IDE
- `windsurf` - Windsurf IDE
- `cline` - Cline extension for VS Code
- `vscode` - VS Code with Cline (same as cline)
- `continue` - Continue extension for VS Code
- `copilot` - GitHub Copilot CLI (experimental)
- `antigravity` - Antigravity IDE

## Support

- **Documentation**: [docs.kusari.cloud](https://docs.us.kusari.cloud/docs/Inspector/)
- **Email**: support@kusari.dev

## License

Apache 2.0 - see [LICENSE](LICENSE) for details.

## Credits

Built by [Kusari](https://kusari.dev)