CodeQL LSP MCP Server (Python)

License: MIT

A local Model Context Protocol server that exposesCodeQL language intelligence to AI coding agents. It starts the language server bundledwith 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 byGitHub. 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 samekind of syntax and semantic feedback an editor gets, without turning the MCP server into ageneral 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. Useof 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 yourmachine:

{
  "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, ordiagnostics. 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 forthe CodeQL language server. The adapter is intentionally isolated underlanguage_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 SecurityVulnerabilities. A separate TypeScript implementationfrom that research team is available atneuralprogram/codeql-lsp-mcp.

License

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

CodeQL LSP MCP Server (Python)