Cursor
Install secrets-detection hooks, the SonarQube MCP Server, and Vortex analysis and Vortex context features for Cursor with the SonarQube CLI.
sonar integrate cursor configures the SonarQube CLI to work alongside Cursor. In an interactive terminal, the command shows these recommended components, then asks you to install them or customize the selection (see Install confirmation):
Secrets detection: a
beforeSubmitPrompthook that scans prompts before they're sent to the model, plus two file-read hooks (beforeReadFileandpreToolUse) that scan files before Cursor reads them. Together they block any operation that would expose a secret.The SonarQube MCP Server, which lets Cursor fetch projects, issues, and rules directly.
Vortex (when your connection has a Vortex subscription: SonarQube Cloud Team (annual) or Enterprise plan, or SonarQube Server 2026.5 or newer Enterprise and Data Center editions): installs Vortex analysis and Vortex context together. It adds:
Vortex analysis instructions as an always-applied rule in
~/.cursor/rules/that tells Cursor to runsonar analyze agenticon your changes at the end of a turnA
sessionStarthook that injects Vortex context when a session starts, letting Cursor use project guidelines, architecture, semantic navigation, and dependency context
Pass --non-interactive to accept every offered component without prompts (see Non-interactive install).
Prerequisites
Cursor is installed.
Install
Install once for this machine:
sonar integrate cursorThe command writes hooks and config to ~/.cursor/ and applies to desktop Cursor sessions on this machine. See Project versus global scope.
Warning: Cursor's cloud and background agents only pick up project-level hooks, not global ones. Desktop Cursor sessions still run the installed hooks.
Note: If a previous install wrote
.agents/skills/sonar-context-augmentation/SKILL.md, update to SonarQube CLI 1.8.0 or newer, then re-runsonar integrate cursorto replace that leftover skill with the session-start hook.
What the command does
The integrator runs in two phases:
Validation. It checks that your saved token can reach SonarQube. On SonarQube Cloud, your connection must include an organization. An invalid token stops setup and tells you to run
sonar auth login. An unreachable server stops setup and asks you to check the server URL and your network connection.Installation. The CLI shows a What will be installed summary of the recommended components (secrets detection, MCP server, and Vortex when eligible). In an interactive terminal, choose Install recommended to write that set, or Customize to accept or decline each component and then press Enter. Components that are not available are skipped with an explanation. In non-interactive mode, every eligible component is installed without prompts. The CLI then writes the accepted components into
~/.cursor/.Common skip reasons include:
Your connection does not have a Vortex subscription (only available with SonarQube Cloud Team (annual) or Enterprise plan, or SonarQube Server 2026.5 or newer Enterprise and Data Center editions).
Secrets hooks
Cursor receives three secrets detection hooks in ~/.cursor/hooks.json:
beforeSubmitPrompt
UserPromptSubmit
The prompt you send to Cursor
beforeReadFile
Read|TabRead
Files before Cursor reads them from disk
preToolUse
Read
Files when the agent issues a Read tool call
The two file-read hooks work together as defense in depth. beforeReadFile intercepts disk reads, but files already open in the editor can bypass it. preToolUse covers agent Read tool calls at a different layer. When either hook detects a secret, Cursor blocks the read and the CLI appends the file to .cursorignore, which blocks subsequent reads natively.
If you're not authenticated or the sonar-secrets binary is missing, all three hooks fail closed and block the operation with a remediation message instead of silently allowing it through. See When scanning is inactive.
Options
--non-interactive
Non-interactive mode (no prompts).
--global, -g
Deprecated since 1.9.0. The install is already global; using the flag prints a warning and does not change the installation scope.
Where files are installed
User home
~/.cursor/ (hooks, rules, MCP config)
Shared binaries
~/.sonar/sonarqube-cli/bin/
State for installed integrations is recorded in ~/.sonar/sonarqube-cli/state.json. See State and storage.
Restart Cursor
Cursor reads its hook and MCP configuration at startup. Restart Cursor for the integration to take effect.
Vortex analysis and Vortex context
When you run sonar integrate cursor against a SonarQube Cloud project, the command writes an always-applied rule in ~/.cursor/rules/sonar-agentic-analysis.mdc that tells Cursor to run sonar analyze agentic --depth DEEP on every file it modified that turn in a single command (repeat --file for each path, or fall back to the git change set). The rule omits --project because each file is analyzed against the project that owns it. In a repository with several projects, the rule tells Cursor to run that command from a directory that contains every file changed in the turn, usually the repository root. Re-run sonar integrate cursor so an existing rule picks up that paragraph. If analysis reports that no project is configured, the rule tells the agent to stay silent for the rest of the session instead of repeating a skip notice. See Files and the project root. Cursor's hook model does not support injecting analysis findings back into the conversation the way Claude Code and Codex hooks do. The CLI uses the same instructions-based pattern as GitHub Copilot CLI.
It also writes a sessionStart hook in ~/.cursor/hooks.json that injects Vortex context when a Cursor session starts. When context cannot load, Cursor asks the agent to tell you once per session. See When Vortex context does not load. If a previous install wrote .agents/skills/sonar-context-augmentation/SKILL.md, update to SonarQube CLI 1.8.0 or newer, then re-run sonar integrate cursor to replace that leftover skill with the session-start hook.
For overviews of these features, see Vortex analysis and Vortex context.
Verify it works
Test the secrets hook
Create a file in your project with a fake-looking but secret-shaped value:
Ask Cursor to read it: "Read secrets.js."
Cursor should block the read and explain that the file contains a secret. The CLI also adds the file to
.cursorignore.
After you've confirmed the hook is active, delete the test file.
Also run sonar system status to confirm the Cursor integration reports Secrets Hook: CONFIGURED. If the hook entry exists but the backing script is missing or malformed, status shows CONFIGURED / INVALID CONFIG and recommends re-running sonar integrate cursor. See Check system status.
Test the MCP server
In Cursor, ask: "Use the SonarQube MCP Server to list my open projects." Cursor should call SonarQube and return your project list. If it does not, run sonar auth status to confirm the underlying token is healthy and restart Cursor. If the connection closes with an error, see MCP server connection closes.
MCP server connection closes
If Cursor logs MCP error -32000: Connection closed and the SonarQube MCP Server does not start, your organization's Cursor Enterprise MCP controls may run the server in a sandbox that blocks access to the container runtime. The SonarQube CLI configures Cursor to start the server with sonar run mcp, and that command starts the MCP server in a local container, which means it cannot start when the sandbox blocks the runtime. Any container-based MCP server fails the same way. Other causes of this error exist, for example a container runtime that is not running.
To fix this, use one of these options:
Ask a Cursor team administrator to add a Command entry that matches
sonar run mcpin Team Settings > MCP Configuration, with the network mode set to No sandbox. Cursor matches Command entries against the full command, including its arguments, and supports*wildcards.Connect Cursor to a SonarQube-hosted MCP server instead. Hosted servers do not run a container on your machine. They expose fewer tools and do not include the Sonar Vortex analysis and context tools.
Test Vortex analysis
In Cursor, make a code change and end the turn. Cursor should run Vortex analysis on your changes per the installed rule. This requires a Sonar Vortex subscription.
Non-interactive install
For provisioning scripts, dotfiles, and onboarding automation:
In non-interactive mode the CLI does not prompt for feature selection, install confirmation, token repair, or feature removal; it installs every component that is not explicitly skipped. When you authenticate with environment variables, integrate commands also run in non-interactive mode even without the flag. Run sonar auth status afterward to confirm everything is configured correctly.
Uninstall
Run sonar integrate cursor again in an interactive terminal and choose Customize. For each installed feature, the CLI asks Keep?: answer No, confirm Proceed with removal?, and the CLI removes hooks, rules, and state for that feature. Vortex is removed as one unit (Vortex analysis rule and session-start hook). See integrations/README.md for the full flow.
For a manual cleanup or non-interactive environments:
Delete the SonarQube hook files and rules written under
~/.cursor/.Remove the SonarQube MCP Server entry from your Cursor configuration.
Remove the integration entry from
~/.sonar/sonarqube-cli/state.json(underintegrations.installed).
See Uninstalling for the full removal procedure.
Related pages
Last updated
Was this helpful?

