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).

Full documentation: docs/BOTNEX_MCP_SERVER.md
NEXA integration context: ../botnex-backend/docs/NEXA_INTEGRATION.md

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.

If Claude or Cursor shows “process exiting early” and the log contains anyio.create_memory_object_stream / TypeError: 'function' object is not subscriptable, the API token is not the problem. The official mcp SDK needs AnyIO 4.5+. Upgrade in the same Python that owns mcp-botnex:

python -m pip install -U "anyio>=4.5" "mcp>=1.9,<2"

Configuration

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

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.

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