Metadata-Version: 2.4
Name: bawbel-mcp
Version: 1.1.0
Summary: MCP server exposing Bawbel Scanner as agent-callable security tools
Author-email: Bawbel <bawbel.io@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://bawbel.io
Project-URL: Repository, https://github.com/bawbel/bawbel-mcp
Project-URL: Documentation, https://bawbel.io/docs
Project-URL: Threat Intel, https://api.piranha.bawbel.io
Keywords: mcp,security,scanner,ave,agentic-ai,prompt-injection,vulnerability,devsecops
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=3.0.0
Requires-Dist: bawbel-scanner>=1.2.2
Provides-Extra: all
Requires-Dist: bawbel-scanner[all]>=1.2.2; extra == "all"
Dynamic: license-file

# Bawbel MCP Server

<!-- mcp-name: io.github.bawbel/bawbel-mcp -->

**Security scanner for MCP servers and agentic AI components, exposed as MCP tools.**

Bawbel MCP Server lets any MCP-compatible agent scan servers, check skill files,
score conformance, manage justified suppressions, and query the AVE threat
intelligence database mid-conversation.

[![PyPI version](https://badge.fury.io/py/bawbel-mcp.svg)](https://pypi.org/project/bawbel-mcp/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/bawbel-mcp.svg)](https://pypi.org/project/bawbel-mcp/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/bawbel-mcp.svg)](https://pypi.org/project/bawbel-mcp/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![AVE Standard](https://img.shields.io/badge/AVE_Records-48-teal.svg)](https://github.com/bawbel/ave)
[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-blue.svg)](https://modelcontextprotocol.io)
[![Powered by](https://img.shields.io/badge/powered_by-bawbel--scanner_v1.2.2-1B5E3F.svg)](https://github.com/bawbel/scanner)

---

## Install

```bash
pip install bawbel-mcp
```

Or with all detection engines (YARA, Semgrep, LLM, Magika, Sandbox):

```bash
pip install "bawbel-mcp[all]"
```

---

## Tools

| Tool | Description |
|---|---|
| `scan_content` | Scan raw text content for AVE vulnerabilities |
| `scan_server_card` | Fetch and scan an MCP server-card before connecting |
| `scan_creds` | Credential-focused scan (API keys, tokens, passwords, private keys) |
| `scan_chain` | Delegation chain scan (unsafe sub-agent spawning and inherited permissions) |
| `check_conformance` | Score a server manifest against the MCP spec (18 checks, A+ to F) |
| `accept_finding` | Insert a justified suppression with reason, reviewer, and optional expiry |
| `lookup_ave` | Get a full AVE record by ID with remediation guidance |
| `search_ave` | Search AVE records by keyword |
| `list_ave` | List all AVE records with optional severity/category filters |
| `check_pins` | Detect rug pull drift in a directory of skill files |

## Resources

| Resource | Description |
|---|---|
| `ave://stats` | Current AVE database statistics |
| `ave://record/{ave_id}` | Full AVE record for a specific ID |

---

## Usage

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "bawbel": {
      "command": "uvx",
      "args": ["bawbel-mcp"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add bawbel uvx bawbel-mcp
```

### Cursor / Windsurf

Add to your MCP settings:

```json
{
  "bawbel": {
    "command": "uvx",
    "args": ["bawbel-mcp"]
  }
}
```

### Remote deployment (Streamable HTTP)

```bash
uvx bawbel-mcp --transport streamable-http --host 0.0.0.0 --port 8000
```

---

## Example conversations

**Scan a server before connecting:**

> "Before I add this MCP server to my config, scan it for security issues:
> https://api.some-mcp-server.com"

Claude calls `scan_server_card("https://api.some-mcp-server.com")` and reports
findings with AVE IDs, AIVSS severity scores, and remediation steps.

**Check a skill file:**

> "Check this skill file content for prompt injection vulnerabilities"

Claude calls `scan_content(content)` and returns findings including any
toxic flow chains detected.

**Check for hardcoded credentials:**

> "Does this skill file contain any hardcoded API keys or secrets?"

Claude calls `scan_creds(content)` and returns credential findings only.

**Check for unsafe delegation:**

> "Does this skill spawn sub-agents without proper trust boundaries?"

Claude calls `scan_chain(content)` and returns delegation chain findings.

**Accept a false positive:**

> "Mark AVE-2026-00001 on line 7 of travel.md as a false positive.
> Reason: internal registry endpoint, not attacker-controlled."

Claude calls `accept_finding(...)` and writes the justified suppression
comment directly into the file. The approval is tracked in version control.

**Score a server against the spec:**

> "Does this server follow the MCP spec? https://api.some-mcp-server.com"

Claude calls `check_conformance("https://api.some-mcp-server.com")` and
returns a score, grade, and list of failed checks.

**Look up a vulnerability:**

> "What is AVE-2026-00041 and how do I fix it?"

Claude calls `lookup_ave("AVE-2026-00041")` and returns the full record
with behavioral fingerprint, IOCs, and remediation steps.

**Search for relevant vulnerabilities:**

> "What AVE records cover credential exfiltration?"

Claude calls `search_ave("credential exfiltration")` and returns matching
records with AIVSS scores and OWASP MCP categories.

**Audit mode - see all findings including suppressed:**

> "Scan this file and show me everything, including suppressed findings."

Claude calls `scan_content(content, no_ignore=True)` and bypasses all
suppression layers.

---

## Requirements

- Python 3.10+
- `bawbel-scanner>=1.2.2` (installed automatically)
- `fastmcp>=3.0.0` (installed automatically)

The `bawbel` CLI must be available in PATH. Installing `bawbel-mcp` installs
`bawbel-scanner` which provides the `bawbel` CLI.

---

## Related

- [bawbel-scanner](https://github.com/bawbel/scanner) - CLI scanner
- [bawbel/ave](https://github.com/bawbel/ave) - AVE standard and records
- [api.piranha.bawbel.io](https://api.piranha.bawbel.io) - Threat intel API
- [bawbel.io/docs](https://bawbel.io/docs) - Full documentation

---

Apache 2.0. Built by [Bawbel](https://bawbel.io).
