This MCP server wraps the CodeQL query server and exposes CodeQL tools via the MCP protocol, enabling tools like Cursor or AI agents to interact with CodeQL through structured MCP commands and document search. It supports registering CodeQL databases, running full queries or quick-evaluations of symbols, decoding .bqrs results into JSON, and locating symbol positions for predicates and classes. After starting, clients can issue MCP commands to register databases, execute queries, and retrieve results in a consistent JSON format suitable for automation and tooling.

Prerequisites:

• Python and uv (via uv package runner) installed on your system
• CodeQL binary available on PATH or specify its path in codeqlclient.py

Installation steps:

1. Install Python dependencies (via uv or pip): uv run mcp install -r requirements.txt

   or directly with pip:

   pip install fastmcp httpx

2. Ensure the CodeQL CLI is accessible:

   • Confirm codeql is in your PATH or set CODEQL_PATH in the environment

3. Run the MCP server: uv run mcp run server.py -t sse

4. Verify the server is listening (default): http://localhost:8000/sse

Notes:

• If you need to customize the CodeQL path, edit codeqlclient.py to hardcode the path.
• Cursor clients expect the server to expose endpoints via SSE at /sse.

Tips and common issues:

• Ensure a codeql binary is available in PATH or configured in codeqlclient.py.
• When deploying, you may want to pin the CodeQL database locations and query write locations in your prompts for deterministic results.
• The server uses SSE for streaming responses; ensure your client supports Server-Sent Events.
• If you modify server.py, keep the JSON-RPC/CodeQL endpoints compatible with CodeQLQueryServer expectations.
• For Cursor or AI agents, you may need to specify database paths and query locations in your prompts to guide the results.