Getting Started

June 29, 2026 · View on GitHub

This guide covers installation, configuration, and usage of the CodeQL Development MCP Server.

Prerequisites

Node.js v25.6.0 or later (nodejs.org)
CodeQL CLI (github.com/github/codeql-cli-binaries)
VS Code with GitHub Copilot extension

If you use ql-mcp inside VS Code or a compatible fork such as Cursor, the VS Code extension (VSIX archive bundle) is the preferred path — it automates installation, configuration, and CodeQL CLI discovery. Download the .vsix from GitHub Releases and install it via Extensions: Install from VSIX… in the Command Palette, or build it from source with npm run package:vsix. See the VS Code Extension guide for details.

For Copilot CLI or other non-IDE agentic tools, use one of the methods below.

From npm

The package is published to the public npm registry. No authentication or special configuration is needed:

# Install globally
npm install -g codeql-development-mcp-server

# Install CodeQL pack dependencies (required on first use)
codeql-development-mcp-server-setup-packs

Note (Windows): The codeql-development-mcp-server-setup-packs command requires a Bash-compatible shell (e.g., Git Bash or WSL). On Windows without Bash, run setup-packs.sh directly from the package's scripts/ directory.

Or use npx to run without a global install:

npx -y codeql-development-mcp-server

Note: The npm package bundles the tool query source packs (.ql files and lock files), but their CodeQL library dependencies (e.g., codeql/javascript-all) must be fetched from GHCR on first use. Run codeql-development-mcp-server-setup-packs once after installing to download them (~/.codeql/packages/). If you skip this step, the codeql_pack_install MCP tool can install dependencies on demand for individual packs.

From GitHub Releases

Download the latest release from Releases
Extract: tar -xzf codeql-development-mcp-server-vX.Y.Z.tar.gz -C /path/to/destination

From Source

git clone --recurse-submodules https://github.com/advanced-security/codeql-development-mcp-server.git
cd codeql-development-mcp-server
npm install && npm run build

VS Code Configuration

Add to your mcp.json file:

OS	Location
macOS	`~/Library/Application Support/Code/User/mcp.json`
Windows	`%APPDATA%\Code\User\mcp.json`
Linux	`~/.config/Code/User/mcp.json`

Using npx (recommended)

{
  "servers": {
    "ql-mcp": {
      "command": "npx",
      "args": ["-y", "codeql-development-mcp-server"],
      "type": "stdio"
    }
  }
}

Using a local path (from source or release archive)

{
  "servers": {
    "ql-mcp": {
      "command": "node",
      "args": ["/path/to/destination/server/dist/codeql-development-mcp-server.js"],
      "type": "stdio"
    }
  }
}

Environment Variables

Variable	Description	Default
`CODEQL_PATH`	Absolute path to the CodeQL CLI binary	`codeql`
`TRANSPORT_MODE`	`stdio` or `http`	`stdio`
`HTTP_PORT`	HTTP port	`3000`
`DEBUG`	Enable debug logging	`false`
`CODEQL_DATABASES_BASE_DIRS`	Colon-separated directories to search for CodeQL databases	—
`CODEQL_QUERY_RUN_RESULTS_DIRS`	Colon-separated directories containing per-run query result subdirectories	—
`CODEQL_MRVA_RUN_RESULTS_DIRS`	Colon-separated directories containing MRVA run result subdirectories	—

Verification

Restart VS Code
Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Run "GitHub Copilot: List MCP Servers"
Confirm ql-mcp appears

Troubleshooting

Tool query errors (e.g., PrintAST fails): Run codeql-development-mcp-server-setup-packs to install CodeQL pack dependencies
Server not listed: Verify absolute path in mcp.json, restart VS Code
CodeQL errors: Run codeql --version to confirm CLI is installed
Permission denied: Check file permissions on server directory

Next Steps

Tools Reference - Available MCP tools
Prompts Reference - MCP prompts for CodeQL workflows
Resources Reference - MCP resources for CodeQL learning