Ditto MCP Server
Allows executing DQL queries against Ditto databases using Docker containers as an alternative runtime environment for the MCP server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Ditto MCP Server show me the top 5 customers by total orders"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Ditto MCP Server — Secure DQL for Ditto
📚 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_dqltool, andditto://configresourceStatement 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.liveA Ditto API key with access to that app
Quick Start (Local)
npx -y ditto-mcp-server@latestDefaults 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@latestInstall 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 20000VS 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– returnspongfor connectivity checkexecute_dql– run a parameterized DQL against Dittostatement(string, required) – single statement, no trailing;args(object, optional) – named parameterstransactionId(number, optional) – X‑DITTO‑TXN‑IDapiKey(string, optional) – override key; prefer envbaseUrl(string, optional) – override base URLtimeoutMs(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.liveDITTO_API_KEY– Ditto API keyMCP_DITTO_ALLOWED–READ,ALL, or a comma list likeSELECT,INSERTMCP_DITTO_QUERY_ALLOW_PATTERNS– comma/semicolon‑separated regex allow‑listDITTO_TIMEOUT_MS– default per‑call timeout (ms)DITTO_API_KEY_ENV– env var name to read API key from (defaultDITTO_API_KEY)MCP_SERVER_NAME– server display nameMCP_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 stdioLinting is TypeScript‑strict by design. The prepack script builds automatically before npm publish.
Test with MCP Inspector
npx -y @modelcontextprotocol/inspector npx ditto-mcp-serverAlternative Runtimes
bunx -y ditto-mcp-serverWindows PowerShell example:
cmd /c npx -y ditto-mcp-serverDocker
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-mcpYou 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_URLandDITTO_API_KEYare setIn Windows, provide full
nodeanddist/index.jspaths 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 toolsexecute_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
Scored across 2 tools
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.
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.
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.
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
Related MCP Connectors
Governed SQL access to your databases: redaction, query review and an audit log.
Draxlr's remote MCP server connects AI assistants to your SQL databases and dashboards. Explore schemas, run read-only queries, manage saved queries and dashboards, and export results, all with row-level security so each user sees only their own data.
Graph-vector database: run Helix queries, read query insights and health, manage databases
Securely query and analyze business data, dashboards, projections, alerts, and knowledge.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA 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
- AlicenseNot gradedqualityCmaintenanceProvides read-only SQL analytics on local CSV, Parquet, and JSON datasets using DuckDB, with pagination, security guardrails, and health monitoring.MIT
- FlicenseNot gradedqualityFmaintenanceProvides read-only SQL query access to Postgres and DuckDB databases via MCP tools, with extensive security hardening for public endpoints.1-
- FlicenseNot gradedqualityDmaintenanceEnables running read-only SQL queries and exploring DuckDB databases through MCP tools like listing tables, describing schemas, and fetching paginated data.-