Zero-X Cursor Plugin & MCP Server

The Zero-X Cursor plugin brings Zero-X's security and analysis capabilities directly into your Cursor IDE via a Python-based Model Context Protocol (MCP) server.

This repository contains:

• Cursor plugin configuration, rules, and commands
• A Python MCP server (zerox_mcp) that communicates with the Zero-X backend

Contents

• .cursor-plugin/plugin.json – Cursor plugin manifest (metadata, logo, keywords, component paths)
• mcp.json – MCP configuration that installs (if needed) and starts the zerox MCP server
• rules/zerox-best-practices.mdc – Always-on rules explaining when and how to use Zero-X tools
• commands/ – Cursor command definitions for running Zero-X scans and explanations
• assets/zerox-logo.svg – Plugin logo for display inside Cursor
• zerox_mcp/ – Python package implementing the Zero-X MCP server
• requirements.txt – Python dependencies for the MCP server

Configuration

The MCP server requires access to the Zero-X backend and an API key.

Environment variables:

• ZEROX_API_KEY – API key for authenticating with the Zero-X backend
• ZEROX_BASE_URL – Base URL for the Zero-X API (default: https://in.zero-x.cloud)
• ZEROX_REQUEST_TIMEOUT – Optional request timeout in seconds (default: 30.0)
• ZEROX_DEBUG – Optional flag (1, true, yes, on) to enable debug logging

You can configure these either in your system environment, or by editing the env section of mcp.json (recommended for local development).

Python virtual environment setup

It is recommended to run the MCP server inside a virtual environment.

python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# On Windows:
# venv\Scripts\activate

pip install -r requirements.txt

Running the MCP server manually

After installing dependencies and setting the required environment variables, you can run the MCP server directly:

python -m zerox_mcp.server

This will start the MCP server on stdin/stdout, which is how Cursor communicates with MCP servers.

Using the plugin in Cursor

1. Open Cursor.
2. Go to Plugins → Load Local Plugin.
3. Select this project folder (zero-x-cursor).
4. Cursor will read .cursor-plugin/plugin.json to display the Zero-X plugin, then read mcp.json.
   • The MCP command uses python in stdio mode.
   • The MCP command checks whether zerox_mcp is installed.
   • If not installed, it installs from the Zero-X GitHub repository.
   • It then starts the server via python -m zerox_mcp.server.
5. The rules/zerox-best-practices.mdc file guides the AI agent on when to call tools such as zerox_full_scan.
6. The commands under commands/ define high-level actions:
   • zerox.scanProject – scan the current project using zerox_full_scan
   • zerox.scanFile – scan the active file using zerox_full_scan
   • zerox.explainFinding – explain a specific finding using zerox_explain_finding

Available MCP tools

The Zero-X MCP server exposes several tools:

• zerox_full_scan – run a full Zero-X scan on one or more files
• zerox_secrets_scan – secrets-focused scan (hardcoded secrets, API tokens, private keys, JWT secrets)
• zerox_sast_scan – SAST-focused scan for insecure code patterns
• zerox_dependency_scan – dependency-focused scan for vulnerable packages
• zerox_get_scan_summary – retrieve a summary of findings for a given scan
• zerox_explain_finding – retrieve a detailed explanation and remediation guidance for a specific finding

Local testing workflow

1. Setup
   • Create and activate a virtual environment.
   • Install dependencies with pip install -r requirements.txt.
   • Set ZEROX_API_KEY (and optionally ZEROX_BASE_URL) in your environment or in mcp.json.
2. Run in Cursor
   • Load the local plugin as described above.
   • Open a file that contains obvious security issues (e.g., hardcoded secrets) and run the zerox.scanFile command.
   • Run zerox.scanProject on a workspace to exercise multi-file scanning.
   • Use zerox.explainFinding on one of the returned findings to see detailed remediation guidance.

Debugging checklist

• If the plugin does not appear in Cursor:
  • Ensure .cursor-plugin/plugin.json is valid JSON and has a lowercase, kebab-case name.
  • Verify the plugin folder was selected correctly when loading the local plugin.
• If the MCP server does not start:
  • Confirm that python (Python 3.9+) is available on your PATH.
  • On Linux, install python-is-python3 if only python3 exists.
  • Check that mcp.json can run its install/start command without local shell restrictions.
  • Run python -m zerox_mcp.server manually and watch for errors in the terminal.
• If scans return no findings or fail:
  • Confirm ZEROX_API_KEY and ZEROX_BASE_URL are set correctly.
  • Ensure that the files argument passed to tools like zerox_full_scan contains both path and content.
  • Enable debug logging by setting ZEROX_DEBUG=1 and re-running the server.

Development notes

• The Python MCP server lives under zerox_mcp/ and is structured for modularity:
  • config.py – configuration and environment handling
  • models.py – Pydantic models for request/response payloads
  • client.py – HTTP client for the Zero-X backend
  • tools/ – individual MCP tool implementations (scanning, reports, explain, etc.)
  • server.py – MCP server bootstrap and tool registration

Refer to the source files in zerox_mcp/ for more details.

Marketplace and versioning

• The plugin manifest version is defined in .cursor-plugin/plugin.json under the version field.
• When preparing a new release:
  • Update the version field.
  • Commit your changes and push to your Git repository.
  • Test the plugin locally in Cursor.
• To publish to the Cursor Marketplace:
  • Push this repository to a public Git hosting provider (for example, GitHub).
  • Visit https://cursor.com/marketplace/publish and submit the repository URL, plugin name (zero-x-cursor), version, and a short description.