An MCP server for q/kdb+ integration for development and debugging workflows.
qmcp Server
A Model Context Protocol (MCP) server for q/kdb+ integration.
MCP is an open protocol created by Anthropic that enables AI systems to interact with external tools and data sources. While currently supported by Claude (Desktop and CLI), the open standard allows other LLMs to adopt it in the future.
Open-Source Proof-of-Concept
This repository contains an open-source proof-of-concept demonstrating the core qmcp approach. The Qython translation tool (available at github.com/gabiteodoru/qython) covers ~5% of the q language and is provided for evaluation and experimentation.
Production Results: The full Qython implementation achieves 0.6% failure rate on HumanEval benchmarks, with 10x reliability improvement over native q development. See the complete evaluation: **0.6% Failure Rate: Solving LLM Code Generation for q/kdb+**
Commercial Licensing: For access to the full Qython implementation with comprehensive language coverage, contact gabiteodoru@gmail.com
Features
- Connect to q/kdb+ servers
- Execute q queries and commands
- Persistent connection management
- Intelligent async query handling with configurable timeouts
- Programmatic query cancellation (Ctrl+C equivalent)
- Graceful handling of long-running queries
- NEW: Qython language translator (Experimental Alpha)
Windows Users: WSL Recommendation
⚠️ Important for Windows users: For optimal functionality, it is highly recommended to run both the MCP server and your q session inside WSL (Windows Subsystem for Linux). This ensures the server can interrupt infinite loops and runaway queries that LLMs might accidentally generate.
Running the MCP server on Windows (outside WSL) disables SIGINT-based query interruption functionality, which is critical for escaping problematic queries during AI-assisted development sessions.
Architecture & Design Philosophy
Intended Goals
qmcp is designed to provide AI coding assistants with controlled access to q/kdb+ databases for development and debugging workflows:
- Development-Focused: Optimized for coding tools working with debug/dev q servers
- Query Control: AI can interrupt long-running queries (equivalent to developer Ctrl+C)
- Predictable Behavior: Sequential execution prevents resource conflicts during development
- Configurable Timeouts: Customizable timing for different development scenarios
Design Logic
The server architecture makes deliberate choices for AI-assisted development workflows:
**Single Connection Model**
- Why: Simplifies development debugging - one connection, clear state
- Benefit: Matches typical developer workflow with single q session
- Implementation: One persistent connection per MCP session
**Sequential Query Execution**
- Why: Development environments don't need concurrent query support
- Benefit: Predictable resource usage, easier debugging, prevents query interference
- Implementation: New queries rejected while another is running
**Smart Async Switching with Configurable Timeouts**
Fast Query (< async switch timeout) → Return result immediately
Slow Query (> async switch timeout) → Switch to async mode
→ Auto-interrupt after interrupt timeout (if configured)
- Why: Keeps AI coding sessions responsive while allowing complex development queries
- Benefit: Immediate feedback for quick queries, progress tracking for analysis
- Customization: All timeouts configurable via MCP tools
**AI-Controlled Query Interruption**
- Why: AI coding tools need ability to cancel runaway queries (like developer Ctrl+C)
- How: MCP server locates q process by port and sends SIGINT after configurable timeout
- Benefit: Prevents development sessions from hanging on problematic queries
- Limitations: SIGINT functionality disabled when:
- MCP server runs on Windows (outside WSL)
- MCP server and q session run on opposite sides of WSL/Windows divide
**Development-Oriented Process Management**
- Why: Coding tools work with user-managed development q servers
- Benefit: Developer controls q server lifecycle, AI controls query execution
- Design: MCP server provides query interruption capability without server lifecycle management
Why This Design Makes Sense for Coding Tools
- Development Workflow: Matches how developers interact with q - single session, iterative queries
- AI Safety: Prevents AI from overwhelming development environments with concurrent requests
- Debugging-Friendly: Sequential execution makes it easier to trace issues
- Responsive: Async handling prevents AI coding sessions from blocking
- Configurable: Timeouts can be tuned for different development scenarios
This architecture provides A
Tools (3)
execute_queryExecute q queries and commands on a connected kdb+ server.qython_translateTranslates Python-like syntax to q using the Qython translator.configure_timeoutsSet async switch and interrupt timeouts for query management.Configuration
{
"mcpServers": {
"qmcp": {
"command": "npx",
"args": ["-y", "@gabiteodoru/qmcp"]
}
}
}