qmcp Server

You can run and use qmcp to connect a q/kdb+ session to an AI-assisted development workflow. This MCP server provides a controlled, interruptible way for AI tools to query and manage q/kdb+ data, with features like persistent connections, smart async handling, and the ability to cancel long-running queries.

How to use

Start by launching a local q server and then run the qmcp server to enable MCP-based interactions. Once connected, you can send q queries, manage timeouts, and interrupt running queries when needed. Use the integration to develop, test, and debug q code with AI assistance in a predictable, sequential workflow.

Typical usage patterns include establishing a persistent q connection, issuing quick queries to get immediate feedback, and escalating to async mode for longer tasks. You can configure timeouts for switching to async mode and for interrupting queries, ensuring the AI tooling remains responsive while giving you control over long or uncertain operations.

How to install

Prerequisites you need before installation: Python 3.8 or newer and access to a q/kdb+ server. You will also use a lightweight installer (uv) for quick trials or pip for a global install.

# Lightweight option (uv) is ideal for trying out quickly
claude mcp add qmcp "uv run qmcp/server.py"  # if you are using Claude CLI

# Full installation with pip (recommended for global use)
pip install qmcp

# Optional: use a virtual environment to isolate dependencies
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install qmcp

# Alternatively, project-specific uv setup
# One-time: uv run qmcp
# Or: uv sync && uv run qmcp

After installation, you can add the MCP server to Claude configurations to enable direct usage from Claude interfaces.

Additional sections

Configuration and runtime details let you tailor how the MCP server interacts with q/kdb+ during development and debugging sessions. The server is designed for a development-focused workflow with a single persistent connection per session, sequential query execution, and configurable timeouts for fast and long-running queries. You can interrupt a running query by sending a SIGINT equivalent after a configurable timeout, which helps you escape problematic AI-generated code.

Environment variables you may need include Q_DEFAULT_HOST, which defines the default connection target in host:port or host:port:auth formats. This lets you quickly connect without repeating full connection details each time.

Known limits and guidance to maximize reliability include running the MCP server and q session within WSL if you are on Windows. This ensures proper support for interrupting queries generated by AI tools and avoids disabling SIGINT-based interruption. The server supports a single connection per session and sequential query execution to keep the workflow predictable during development.

Available tools

connect_to_q

Establishes a connection to a q/kdb+ server with flexible fallback logic for host/port/auth details, enabling a persistent session.

query_q

Executes q queries with intelligent timeout handling and options for switching to async mode when necessary.

set_timeout_switch_to_async

Configures the time threshold at which long-running queries shift to asynchronous processing to maintain responsiveness.

set_timeout_interrupt_q

Configures the timeout after which the server sends a SIGINT equivalent to interrupt a running query.

set_timeout_connection

Configures the overall connection timeout behavior for establishing or maintaining a session.

get_timeout_settings

Retrieves the current timeout configuration for quick reference and adjustments.

get_current_task_status

Checks the status of an ongoing asynchronous query.

get_current_task_result

Retrieves the result of a completed asynchronous query.

interrupt_current_query

Sends a SIGINT to interrupt the currently running query.

translate_qython_to_q

Experimental alpha tool translating Python-like syntax to q for experimentation.

translate_q_to_qython

Experimental alpha tool translating q expressions to Python-like syntax with AI disambiguation.