Skip to main content
Glama
CodeQL LSP MCP Server

CodeQL LSP MCP Server

by flyfei-cmd

CodeQL LSP MCP Server (Python)

CI License: MIT

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.

Related MCP server: codeql-lsp-mcp

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.

Available Tools

7 tools
codeql_completeA

Provides code completions at a specific position in a CodeQL file.

Args: file_uri: URI of the CodeQL file line: 0-based line number character: 0-based character position trigger_character: Character that triggered completion (optional) limit: Maximum number of completions to return (default: 50) offset: Offset for pagination (default: 0)

Returns: Dictionary with completion items and metadata

Inputs: line (required), file_uri (required), character (required), limit, +2 more. Returns: object

codeql_definitionA

Navigates to the definition of a symbol.

Args: file_uri: URI of the CodeQL file line: 0-based line number character: 0-based character position

Returns: Dictionary with definition locations and metadata

Inputs: line (required), file_uri (required), character (required). Returns: object

codeql_diagnosticsA

Retrieves diagnostics (syntax/semantic warnings, errors) for a file.

Args: file_uri: URI of the CodeQL file

Returns: Dictionary with diagnostics and metadata

Inputs: file_uri (required). Returns: object

codeql_formatA

Formats a CodeQL file according to standard conventions.

Args: file_uri: URI of the CodeQL file start_line: Start line for range formatting (optional) start_character: Start character for range formatting (optional) end_line: End line for range formatting (optional) end_character: End character for range formatting (optional)

Returns: Dictionary with text edits and metadata

Inputs: file_uri (required), end_line, start_line, end_character, +1 more. Returns: object

codeql_hoverA

Retrieves hover information (documentation, type information) at a specific position.

Args: file_uri: URI of the CodeQL file line: 0-based line number character: 0-based character position

Returns: Dictionary with hover information and metadata

Inputs: line (required), file_uri (required), character (required). Returns: object

codeql_referencesA

Finds all references to a symbol at a specific position.

Args: file_uri: URI of the CodeQL file line: 0-based line number character: 0-based character position

Returns: Dictionary with reference locations and metadata

Inputs: line (required), file_uri (required), character (required). Returns: object

codeql_update_fileA

Updates the content of an open CodeQL file in the language server.

Allows dynamic modification and analysis of unsaved changes.

Args: file_uri: URI of the CodeQL file content: New complete content of the file

Returns: Dictionary with success message and metadata

Inputs: content (required), file_uri (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool serves a distinct LSP feature: completion, hover, definition, references, diagnostics, formatting, and file updates. There is no overlap or ambiguity between the tools.

    Naming Consistency5/5

    All tools follow a consistent codeql_ prefix followed by a clear, lower_snake_case feature name. This uniform namespace makes the toolset predictable and easy to navigate.

    Tool Count5/5

    Seven tools is a well-scoped number for a language server adapter. Each tool covers a common editor interaction, and there is no bloat or unnecessary overlap.

    Completeness4/5

    The toolset covers core LSP features (completion, hover, definitions, references, diagnostics, formatting, and content updates) but omits some common capabilities like rename or document symbols. These gaps are minor and agents can work around them.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to leverage VS Code's language intelligence for code navigation, refactoring, and analysis via the MCP protocol.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Wraps the CodeQL Language Server Protocol to enable LLM agents to write CodeQL queries with intelligent code completion, hover information, and other language features.
      9
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to query language intelligence over MCP, including definitions, references, symbols, and code relationship graphs across many languages, all in one native process with no external language servers.
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides any MCP-capable coding agent with shared, warm language-server intelligence and project-local configuration, so diagnostics, definitions, references, hover, symbols, code actions, formatting, rename, and sync behave consistently across harnesses and sessions. This lets users switch agent tools without reconfiguring LSP integrations or falling back to CLI verification.
      4 npm
      MIT