CodeQL LSP MCP Server (Python)

A local Model Context Protocol server that exposes CodeQL language intelligence to AI coding agents. It starts the language server bundled with the CodeQL CLI and provides MCP tools for completion, hover, definitions, references, diagnostics, formatting, and in-memory file updates.

This is an independent, unofficial project. It is not affiliated with or endorsed by GitHub. The CodeQL CLI is distributed separately under GitHub's own terms.

Why this exists

LLMs can generate plausible QL that does not compile. This bridge gives an agent the same kind of syntax and semantic feedback an editor gets, without turning the MCP server into a general shell wrapper around the CodeQL CLI.

Tools

Tool	Purpose
codeql_complete	Get paginated completions at a position
codeql_hover	Retrieve documentation and type information
codeql_definition	Navigate to a symbol definition
codeql_references	Find references to a symbol
codeql_diagnostics	Collect syntax and semantic diagnostics
codeql_format	Request full-document or range formatting
codeql_update_file	Update an open document in memory

Positions are zero-based, following the Language Server Protocol.

Requirements

• Python 3.10-3.12
• CodeQL CLI on PATH, or an absolute path in CODEQL_PATH
• A workspace containing the QL files and packs you want to inspect

Download the complete CodeQL bundle so the CLI has compatible queries and libraries. Use of CodeQL is subject to the GitHub CodeQL terms and conditions.

Install

From a checkout:

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

Verify the prerequisites:

codeql version
codeql execute language-server --help

Configure an MCP client

The server uses stdio by default. Replace the example paths with absolute paths on your machine:

{
  "mcpServers": {
    "codeql": {
      "command": "/absolute/path/to/codeql-lsp-mcp-python/.venv/bin/codeql-lsp-mcp",
      "env": {
        "CODEQL_PATH": "/absolute/path/to/codeql/codeql",
        "WORKSPACE_PATH": "/absolute/path/to/your/ql-workspace"
      }
    }
  }
}

You can also run it directly:

CODEQL_PATH=codeql WORKSPACE_PATH=/path/to/ql-workspace codeql-lsp-mcp

Set CODEQL_LSP_TRACE=1 to enable verbose LSP protocol tracing while debugging.

Example tool call

{
  "name": "codeql_diagnostics",
  "arguments": {
    "file_uri": "file:///absolute/path/to/ql-workspace/query.ql"
  }
}

For unsaved content, call codeql_update_file before requesting completions, hover, or diagnostics. Files must be inside WORKSPACE_PATH.

Development

python -m pip install -e '.[dev]'
ruff check .
pytest
python -m build

Unit tests do not require CodeQL. A local smoke test can be run with:

CODEQL_PATH=codeql WORKSPACE_PATH=/path/to/ql-workspace \
  pytest -m integration

Design notes

multilspy does not natively expose CodeQL, so this project contains a small adapter for the CodeQL language server. The adapter is intentionally isolated under language_servers/ and pins the known-compatible multilspy release.

The tool interface was inspired by the CodeQL LSP interface described in the FineNib / QLCoder research. See QLCoder: A Query Synthesizer for Static Analysis of Security Vulnerabilities. A separate TypeScript implementation from that research team is available at neuralprogram/codeql-lsp-mcp.

License

MIT. CodeQL itself is not included in this repository and has separate license terms.