mcp-botnex 0.1.1

MCP Server for BotNEX - VAPT scans, reports and CVE intelligence for AI clients

mcp-botnex

MCP (Model Context Protocol) server for BotNEX — exposes VAPT scans, reports, and CVE intelligence to AI clients such as Cursor and the NEXA platform. It is a thin, secure bridge to the existing botnex-backend REST API and authenticates with a user-scoped API token (no JWT).

Features

• 10 tools for scan lifecycle, reports, and CVE lookup
• 6 resources (botnex://…) for @-mentionable context in Cursor
• Dual transport: stdio (Cursor / Claude Desktop) and HTTP (NEXA / Docker)
• API-token auth mapped per-user on the backend — RBAC enforced server-side
• AI-friendly formatters (severity-first findings, normalized CVE output)

Installation

pip install mcp-botnex

Authentication

1. Log in to the BotNEX UI.
2. Create an API token: API Tokens → Create (calls POST /api/v1/users/api-tokens/).
3. Copy the raw token once and provide it to the MCP server via BOTNEX_API_KEY.

The token is sent as Authorization: Bearer <token> on every backend request. The backend resolves it to your user account and enforces all authorization and per-user data scoping.

Configuration

Variable	Required	Default	Description
BOTNEX_BACKEND_URL	Yes	–	Backend origin, e.g. https://botnex.example.com (no /api/v1)
BOTNEX_API_KEY	Yes	–	User API token
BOTNEX_MCP_SERVER_PORT	No	8001	HTTP mode port
BOTNEX_LOG_LEVEL	No	INFO	Log level
BOTNEX_BACKEND_TIMEOUT	No	60.0	Backend HTTP timeout (s)
BOTNEX_FINDINGS_PAGE_SIZE	No	50	Default findings page size

See .env.example for the full list.

Usage — Cursor (stdio)

Add to your Cursor MCP config:

{
  "mcpServers": {
    "botnex": {
      "command": "mcp-botnex",
      "env": {
        "BOTNEX_BACKEND_URL": "https://botnex.example.com",
        "BOTNEX_API_KEY": "your-api-token"
      }
    }
  }
}

Usage — HTTP (NEXA / Docker)

mcp-botnex-http
# or
uvicorn botnex_mcp.http_server:app --host 0.0.0.0 --port 8001

Endpoints: GET /mcp/tools, POST /mcp/tools/call, GET /mcp/resources, POST /mcp/resources/read, GET /health.

Tools

Tool	Description
list_scans	List the user's scans and statuses
trigger_scan	Start a security or asset-discovery scan
get_scan_findings	Paginated, severity-ordered findings for a scan
get_scan_summary	Aggregated dashboard summary
list_scheduled_scans	Upcoming scheduled scans
generate_report	Generate a PDF/CSV/DOCX report
get_report	Report metadata by id
search_cves	Full-text CVE search
get_cve_by_id	CVE detail by id
search_cves_by_vendor	CVEs by vendor + version

Resources

URI	Description
botnex://scans/all	All scans
botnex://scans/summary	Scan dashboard summary
botnex://scans/scheduled	Scheduled scans
botnex://scan/{scan_id}/findings	Findings for a scan
botnex://cve/{cve_id}	CVE detail
botnex://cve/latest	Latest CVEs

Development

pip install -e ".[dev]"
pytest

License

MIT