qmcp Server

- 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)

⚠️ 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.

qmcpis designed to provide AI coding assistants withcontrolled accessto 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

The server architecture makes deliberate choices for AI-assisted development workflows:

- Why: Simplifies development debugging - one connection, clear state
- Benefit: Matches typical developer workflow with single q session
- Implementation: One persistent connection per MCP session

- 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

- 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

- 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

This architecture provides AI coding assistants with effective q/kdb+ access while maintaining the predictable, controlled environment that development workflows require.

- Python 3.8+
- Access to a q/kdb+ server
- uv(for lightweight installation) orpip(for full installation)

For first-time users, the fastest way to get started:

claude mcp add qmcp "uv run qmcp/server.py"

> connect to port 5001 and compute 2+2 ● qmcp:connect_to_q (MCP)(host: "5001") ⎿ true ● qmcp:query_q (MCP)(command: "2+2") ⎿ 4

Lightweight Installation (Claude CLI only)

Run directly with uv (no pip installation required, may be slower on startup; best for trying it out at first):

claude mcp add qmcp "uv run qmcp/server.py"

Option 1: pip (recommended for global use)

Note: Consider using a virtual environment to avoid dependency conflicts:

python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install qmcp

# One-time execution (downloads dependencies each time) uv run qmcp # Or for frequent use, sync dependencies first uv sync uv run qmcp

After full installation, add the server to Claude CLI:

Add to your Claude Desktop configuration file:

{ "mcpServers": { "qmcp": { "command": "qmcp" } } }

When using the MCP server, be aware of these limitations:

- Windows Platform: Query interruption disabled when MCP server runs on Windows (outside WSL)
- Cross-Platform Setup: Query interruption disabled when MCP server and q session run on opposite sides of WSL/Windows divide
- Impact: LLM cannot automatically escape infinite loops or cancel runaway queries in these configurations

- Keyed tables: Operations like1!tablemay fail during pandas conversion
- String vs Symbol distinction: q strings and symbols may appear identical in output
- Type ambiguity: Use q'smetaandtypecommands to determine actual data types when precision matters
- Pandas conversion: Some q-specific data structures may not convert properly to pandas DataFrames

meta table / Check table column types and structure type variable / Check variable type

Skip this section if you're not on Windows.

Since Claude CLI is WSL-only on Windows, but you might want to use Windows IDEs or tools to connect to your q server, you need proper port communication between WSL2 and Windows.

WSL2 Configuration for Port Communication

Location:C:\Users\{YourUsername}\.wslconfig

# Mirrored networking mode for seamless port communication networkingMode=mirrored dnsTunneling=true firewall=true autoProxy=true

Run from Windows PowerShell/CMD (NOT from within WSL):

wsl --shutdown # Wait a few seconds, then start WSL again

# In WSL2, start a server python3 -m http.server 8000 # In Windows browser or PowerShell curl http://localhost:8000

# In Windows PowerShell python -m http.server 8001 # In WSL2 curl http://localhost:8001

- ✅ Direct localhost communication both ways
- ✅ No manual port forwarding needed
- ✅ Better VPN compatibility
- ✅ Simplified networking (Windows and WSL2 share network interfaces)
- ✅ Firewall rules automatically handled

Issue: Port 5000 has limited mirrored networking support due to Windows service binding.

- Windowssvchostservice binds to127.0.0.1:5000(localhost only)
- Localhost-only bindings are not fully mirrored between Windows and WSL2
- This creates an exception to the general mirrored networking functionality

- ✅ Windows ↔ Windows: Works (same localhost)
- ❌ WSL2 ↔ Windows: Fails (different localhost interpretation)
- ✅ WSL2 ↔ WSL2: Works (same environment)
- Use different ports: 5001, 5002, etc. (recommended)
- Stop Windows service: If not needed
- Traditional port forwarding: For specific use cases

Common Services That May Have Localhost-Only Binding

- Flask development servers(default127.0.0.1:5000)
- UPnP Device Host service
- Windows Media Player Network Sharing
- Various development tools

Known Limitations of Mirrored Networking

Official MCP server for dbt (data build tool) providing integration with dbt Core/Cloud CLI, project metadata discovery, model information, and semantic layer querying capabilities.

Query and analyze data with MotherDuck and local DuckDB

A collection of tools for managing the platform, addressing data quality and reading and writing to Teradata Database.

A read-only MCP server for Avro data sources, powered by the CData JDBC Driver.

Run SQL queries on data in Amazon S3 using AWS Athena.

Interact with Bauplan data tables and run queries.

Production-grade MCP server for Databricks: SQL Warehouses, Jobs API, multi-workspace support.

Visual no-code generator that turns any database into multiple scoped MCP servers — one per access group, with PII masking and fail-closed query scoping built in.

A read-only MCP server by CData that enables LLMs to query live data from EnterpriseDB databases.