Skip to main content
Glama
Ditto MCP Server

Ditto MCP Server

by evtapps

Ditto MCP Server — Secure DQL for Ditto

NPM Version MIT licensed Node >=18

Install in Cursor

📚 Table of Contents

Related MCP server: duckdb_analytics_mcp

Overview

An open‑source Model Context Protocol server that executes Ditto DQL over HTTPS with capability gating and safety checks. Designed for Cursor, Claude Code, VS Code Copilot Chat (MCP), Windsurf, Zed, and more.

Features

  • Ping health tool, execute_dql tool, and ditto://config resource

  • Statement guardrails: single statement, operation allow‑list, optional query pattern allow‑list

  • Config via env, CLI, or client config

  • Native ESM, strict TypeScript, zero runtime deps beyond MCP SDK

Requirements

  • Node.js >= 18.17

  • A Ditto app base URL, e.g. https://MY_APP.cloud.ditto.live

  • A Ditto API key with access to that app

Quick Start (Local)

npx -y ditto-mcp-server@latest

Defaults to stdio transport. Provide env vars (recommended):

export DITTO_BASE_URL="https://MY_APP.cloud.ditto.live"
export DITTO_API_KEY="YOUR_API_KEY"
export MCP_DITTO_ALLOWED="READ"   # or ALL / SELECT,INSERT,...

npx -y ditto-mcp-server@latest

Install in Clients

Below are minimal JSON snippets. See each client’s docs for full syntax and options.

Cursor

Add to ~/.cursor/mcp.json or project .cursor/mcp.json:

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server@latest"],
      "env": {
        "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
        "DITTO_API_KEY": "YOUR_API_KEY",
        "MCP_DITTO_ALLOWED": "READ"
      }
    }
  }
}

Claude Code CLI

claude mcp add ditto -- npx -y ditto-mcp-server --timeout 20000

VS Code Copilot Chat (Insiders)

{
  "mcp": {
    "servers": {
      "ditto": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "ditto-mcp-server"],
        "env": {
          "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
          "DITTO_API_KEY": "YOUR_API_KEY"
        }
      }
    }
  }
}

Windsurf

Add to Windsurf MCP config (see their docs for exact path):

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server"],
      "env": {
        "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
        "DITTO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "Ditto": {
      "command": {
        "path": "npx",
        "args": ["-y", "ditto-mcp-server"]
      }
    }
  }
}

Roo Code / Cline

Add in settings under MCP servers or marketplace manual JSON:

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server"],
      "env": {
        "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
        "DITTO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

JetBrains AI Assistant

Settings → Tools → AI Assistant → MCP → Add → As JSON:

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server"],
      "env": {
        "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
        "DITTO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

LM Studio

Program → Install → Edit mcp.json:

{
  "mcpServers": {
    "Ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server"],
      "env": {
        "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
        "DITTO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Warp

Settings → AI → Manage MCP servers:

{
  "Ditto": {
    "command": "npx",
    "args": ["-y", "ditto-mcp-server"],
    "start_on_launch": true
  }
}

Amazon Q Developer CLI

~/.aws/q/developer/cli/config.json:

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server"]
    }
  }
}

Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server"]
    }
  }
}

Tools & Resources

  • ping – returns pong for connectivity check

  • execute_dql – run a parameterized DQL against Ditto

    • statement (string, required) – single statement, no trailing ;

    • args (object, optional) – named parameters

    • transactionId (number, optional) – X‑DITTO‑TXN‑ID

    • apiKey (string, optional) – override key; prefer env

    • baseUrl (string, optional) – override base URL

    • timeoutMs (number, optional, <= 60000)

  • Resource: ditto://config – redacted runtime config

Example: SELECT with named args

Tool: execute_dql
Args:
{
  "statement": "SELECT * FROM collection WHERE type = :t LIMIT 5",
  "args": { "t": "note" }
}

Returns a JSON envelope with items, queryType, warnings, and optional error.

Configuration

You can configure via env, CLI, or client configs. Env is preferred for secrets.

Environment variables:

  • DITTO_BASE_URL – e.g. https://MY_APP.cloud.ditto.live

  • DITTO_API_KEY – Ditto API key

  • MCP_DITTO_ALLOWED – READ, ALL, or a comma list like SELECT,INSERT

  • MCP_DITTO_QUERY_ALLOW_PATTERNS – comma/semicolon‑separated regex allow‑list

  • DITTO_TIMEOUT_MS – default per‑call timeout (ms)

  • DITTO_API_KEY_ENV – env var name to read API key from (default DITTO_API_KEY)

  • MCP_SERVER_NAME – server display name

  • MCP_SERVER_VERSION – overrides the reported server version (default: package.json version; fallback: 0.0.0-dev)

  • LOG_LEVEL – controls logging verbosity: debug|info|warn|error|silent (default: info)

Configuration precedence: CLI flags > environment variables. Reported version precedence: MCP_SERVER_VERSION > package.json > 0.0.0-dev.

CLI flags (subset):

ditto-mcp [transport] \
  --name <name> \
  --base-url <url> \
  --api-key-env <VAR> \
  --timeout <ms>

Transport argument defaults to stdio. This package currently exposes stdio only.

MCP Client One‑click Patterns

  • Cursor deeplink button above for instant install into ~/.cursor/mcp.json.

Security Notes

  • Prefer environment variables for secrets; avoid CLI args containing secrets

  • Allowed operation gating and optional regex allow‑list help constrain queries

  • Logs redact tokens and obvious secret patterns

Development

yarn
yarn build
node dist/index.js stdio

Linting is TypeScript‑strict by design. The prepack script builds automatically before npm publish.

Test with MCP Inspector

npx -y @modelcontextprotocol/inspector npx ditto-mcp-server

Alternative Runtimes

bunx -y ditto-mcp-server

Windows PowerShell example:

cmd /c npx -y ditto-mcp-server

Docker

Build the image:

docker build -t ditto-mcp .

Run with env vars:

docker run --rm -i \
  -e DITTO_BASE_URL="https://MY_APP.cloud.ditto.live" \
  -e DITTO_API_KEY="YOUR_API_KEY" \
  ditto-mcp

You can also configure Docker as a local MCP command in clients that support running a container for stdio transport. Example:

{
  "mcpServers": {
    "ditto": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "DITTO_BASE_URL",
        "-e",
        "DITTO_API_KEY",
        "ditto-mcp"
      ],
      "env": {
        "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
        "DITTO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Troubleshooting

  • If tools don’t appear, refresh/toggle the server in your client

  • Ensure DITTO_BASE_URL and DITTO_API_KEY are set

  • In Windows, provide full node and dist/index.js paths if needed

If your client has trouble auto-installing via npx, try bunx -y ditto-mcp-server.

Versioning & Changelog

See CHANGELOG.md.

License

MIT © EVT Engineering and contributors


This project is not affiliated with Ditto. “Ditto” is a respective trademark of its owner.

Available Tools

2 tools
execute_dqlDitto: Execute DQL queryC

Runs a query in Ditto using a parameterized DQL statement

Inputs: statement (required), args, transactionId, apiKey, +2 more.

pingPingB

Health check for the Ditto MCP server

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct purposes: execute_dql is for running database queries, while ping is a health check. There is no overlap or ambiguity between these functions.

    Naming Consistency4/5

    Both tools follow a verb_noun pattern (execute_dql, ping), though ping is a single word rather than a compound. The naming is consistent in style and readable, with only a minor deviation for the simpler ping.

    Tool Count2/5

    With only 2 tools, the server feels thin for a database query server. While execute_dql is core, the lack of additional tools for operations like schema inspection, data manipulation, or connection management suggests an incomplete surface.

    Completeness2/5

    For a Ditto database server, the tool surface is severely incomplete. It only provides query execution and a health check, missing essential operations such as listing tables, describing schemas, inserting/updating data, or managing transactions, which will limit agent capabilities.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A production-ready MCP server that enables safe, read-only SQL SELECT queries against PostgreSQL databases with built-in security validation. It features connection pooling, automatic row limits, and structured logging to ensure secure and reliable database interactions.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides read-only SQL analytics on local CSV, Parquet, and JSON datasets using DuckDB, with pagination, security guardrails, and health monitoring.
      MIT
    • F
      license
      Not graded
      quality
      F
      maintenance
      Provides read-only SQL query access to Postgres and DuckDB databases via MCP tools, with extensive security hardening for public endpoints.
      1
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables running read-only SQL queries and exploring DuckDB databases through MCP tools like listing tables, describing schemas, and fetching paginated data.
      -