ZapQL MCP Server

Autonomous SQL Server query optimizer via the Model Context Protocol. Connect Claude (or any MCP-compatible agent) directly to your SQL Server and get instant query analysis and AI-powered optimization suggestions.

Quick Start

1. Get an API key

Sign up at zapql.com and create an API key on the dashboard.

2. Add to your editor

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "zapql": {
      "command": "npx",
      "args": ["zapql-mcp"],
      "env": {
        "ZAPQL_API_KEY": "<key from zapql.com dashboard>",
        "SQL_CONNECTION_STRING": "Server=your-server;Database=your-db;User Id=your-user;Password=your-pass;TrustServerCertificate=true"
      }
    }
  }
}

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "zapql": {
      "command": "npx",
      "args": ["zapql-mcp"],
      "env": {
        "ZAPQL_API_KEY": "<key from zapql.com dashboard>",
        "SQL_CONNECTION_STRING": "Server=your-server;Database=your-db;User Id=your-user;Password=your-pass;TrustServerCertificate=true"
      }
    }
  }
}

3. Restart your editor

ZapQL tools will appear automatically. Ask your AI agent to "connect to my database and find the slowest queries."

Optional environment variables

LITELLM_API_KEY=your-openai-key   # BYOK — use your own LLM for optimization
LITELLM_MODEL=gpt-4               # default: gpt-4
ZAPQL_TOP_N=20                     # max optimization suggestions

Tools

connect_database

Establish a connection to a SQL Server instance.

Input:  connectionString (string)
Output: connection status, server info, database name

analyze_query

Analyze a SQL query for performance issues without executing it.

Input:  connectionString (string), queryText (string)
Output: issues list, complexity score, execution plan, suggestions

Detects: SELECT *, missing WHERE clause, leading wildcards, N+1 patterns, NOT IN subqueries, excessive OR conditions, implicit conversions.

optimize_query

Get AI-powered optimization suggestions for a slow query.

Input:  connectionString (string), originalQuery (string), context? (string)
Output: optimizedQuery, explanation, performance comparison, cost improvement estimate

Requires LITELLM_API_KEY. Results are cached in SQLite at ~/.zapql/cache.db.

MCP Resources

| Resource | Description | |----------|-------------| | zapql:///connections | List of active database connections | | zapql:///queries/{connection} | Recent queries for a connection | | zapql:///optimization/{queryId} | Cached optimization result |

Architecture

Claude Desktop
     │  MCP Protocol (stdio)
     ▼
ZapQL MCP Server (Node.js)
     ├── Tools: connect_database, analyze_query, optimize_query
     ├── Resources: connections, queries, optimization results
     ├── SQLServerDriver (mssql) ──→ Your SQL Server
     ├── QueryCache (in-memory + SQLite persistence)
     └── LiteLLM ──→ OpenAI / any LLM provider

Development

npm run build       # Compile TypeScript
npm test            # Run unit tests (node:test)
npm run dev         # Run with tsx (no compile step)
npm run lint        # Type-check without emit

Tests run against dist/ (compiled output). No SQL Server connection required for unit tests — the SQL driver is mocked.

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | SQL_CONNECTION_STRING | ✅ | — | mssql connection string | | ZAPQL_API_KEY | ✅ | — | Internal API key (any string) | | LITELLM_API_KEY | — | — | Enables optimize_query | | LITELLM_MODEL | — | gpt-4 | LLM model for optimization | | ZAPQL_TOP_N | — | 20 | Max optimization suggestions |

Config file: ~/.zapql/.env (loaded automatically on startup)

Logs

Log files at ~/.zapql/logs/zapql-YYYY-MM-DD.log. Structured JSON. Rotates daily, keeps 7 days.

Status

• ✅ MCP tools: connect_database, analyze_query, optimize_query
• ✅ MCP resources: connections, queries, optimization
• ✅ SQLite state persistence
• ✅ In-memory query cache with TTL
• ✅ Comprehensive error handling
• ⏳ Integration tests (US-016)