mcp-botnex 0.1.3

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

• 8 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
BOTNEX_SCAN_PAGE_SIZE	No	25	Default page size for scan list resources
BOTNEX_CVE_PAGE_SIZE	No	20	Default page size for botnex://cve/latest

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
search_cves	Full-text CVE search
get_cve_by_id	CVE detail by id

Resources

All list resources are paginated and field-slimmed to keep responses small and the LLM context cheap. Pagination is controlled with ?page= and ?size= query parameters; size is capped at 100.

URI	Paginated	Description
botnex://scans/all	Yes	Slim list of the user's scans
botnex://scans/summary	–	Aggregated severity counts and risk metrics
botnex://scans/scheduled	Yes	Upcoming scheduled scans
botnex://scan/{scan_id}/findings	Yes	Severity-ordered findings for a scan
botnex://cve/{cve_id}	–	Compact CVE summary
botnex://cve/latest	Yes	Most recently published CVEs

Examples:

• botnex://scans/all?page=2&size=20
• botnex://scan/<scan_id>/findings?page=2&size=25
• botnex://cve/latest?page=1&size=10

Paginated resources return:

{"items": [...], "page": 2, "size": 20, "total": 47, "pages": 3, "has_more": true}

Development

pip install -e ".[dev]"
pytest

License

MIT