CodeQL LSP MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@CodeQL LSP MCP Server show me diagnostics for query.ql"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: codeql-lsp-mcp
Tools
Tool | Purpose |
| Get paginated completions at a position |
| Retrieve documentation and type information |
| Navigate to a symbol definition |
| Find references to a symbol |
| Collect syntax and semantic diagnostics |
| Request full-document or range formatting |
| 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 inCODEQL_PATHA 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 --helpConfigure 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-mcpSet 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 buildUnit tests do not require CodeQL. A local smoke test can be run with:
CODEQL_PATH=codeql WORKSPACE_PATH=/path/to/ql-workspace \
pytest -m integrationDesign 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 toolscodeql_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
Scored across 7 tools
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.
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.
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.
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
Related MCP Connectors
Lean 4 MCP server: compile, prove theorems, and formalize math with Mathlib.
The official Svelte MCP server providing docs and autofixing tools for Svelte development
Build, test, publish, and run Kovca workflows from AI agents over remote MCP.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to leverage VS Code's language intelligence for code navigation, refactoring, and analysis via the MCP protocol.MIT
- AlicenseNot gradedqualityDmaintenanceWraps the CodeQL Language Server Protocol to enable LLM agents to write CodeQL queries with intelligent code completion, hover information, and other language features.9MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseNot gradedqualityCmaintenanceProvides 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 npmMIT