@seed-ship/duckdb-mcp-native
v1.7.3
Published
Native Node.js/TypeScript implementation of DuckDB MCP extension
Maintainers
Readme
DuckDB MCP Native
Native TypeScript implementation of DuckDB MCP (Model Context Protocol) server with federation, graph algorithms, and human-in-the-loop security.
v1.7.3 — Maintenance release on DuckDB 1.5.6 (forward-compatible credential reset, test tooling update). DuckDB is pinned to 1.5.6 (@duckdb/node-api 1.5.6-r.2).
Security update: users of 1.6.2 and earlier should upgrade to 1.7.0 or later (1.7.3 recommended) and enable
MCP_SECURITY_MODE=productionorMCP_SANDBOX=strictwhen SQL can be influenced by untrusted input. Restart the process after updating. Review the security settings and compatibility changes: strict mode disables external data access, including S3. We thank Zureno for reporting this issue through coordinated disclosure.
npm install @seed-ship/[email protected]For CLI/MCP configurations using npx, select @seed-ship/[email protected] explicitly and restart the MCP client. Updating this package does not automatically update already installed or pinned versions.
Features
- 32+ MCP Tools: SQL queries, schema inspection, CSV/Parquet loading, federation, graph algorithms, process mining, data helpers
- 8 Graph Algorithm Tools: PageRank, eigenvector, community detection, modularity, weighted paths, temporal analysis, period comparison, multi-format export
- Layered Security: production mode disables external access in DuckDB (including local files, HTTP and S3) and gates destructive SQL via HITL elicitation
- Federation: Distributed queries across multiple MCP servers with
mcp://URIs - Virtual Filesystem: Direct SQL access via
mcp://URIs with auto-format detection - Transports: stdio, WebSocket, TCP (HTTP client-side)
- Process Mining: 3 tools for workflow analysis from Parquet files
- DuckLake-style Snapshots: built-in lightweight snapshots + time travel on Parquet files (self-contained emulation; the official
ducklakeextension is separately installable on DuckDB ≥ 1.5.2) - DuckPGQ: SQL:2023 property graph queries + native CSR algorithms (PageRank, WCC, clustering)
- Onager (opt-in): ~64 native graph analytics functions (53 table + 11 scalar: betweenness, louvain, dijkstra, link prediction, …) via
ENABLE_ONAGER=true— alpha extension - Geospatial Graphs: GEOMETRY + CRS vertex tables work with DuckPGQ graph algorithms
- MCP SDK 1.32.1: Elicitation API and connect() guard
Version and Compatibility
| Component | Locked or validated version |
| --------------------------- | --------------------------------------------------------- |
| @duckdb/node-api | 1.5.6-r.2 (exact pin; DuckDB 1.5.6) |
| DuckPGQ community extension | 61f5d082 validated on DuckDB 1.5.6; not revision-pinned |
| @modelcontextprotocol/sdk | 1.32.1 |
| Axios / dotenv / ws / Zod | 1.20.0 / 17.4.2 / 8.21.3 / 4.6.5 |
DuckDB is pinned to 1.5.6 (bumped from 1.5.4): upgrading its Node API requires a matching DuckPGQ binary for the target DuckDB version and platform, followed by native graph-query validation. Keep the exact @duckdb/node-api pin when updating other dependencies. DuckPGQ is installed separately with INSTALL duckpgq FROM community: 61f5d082 identifies the revision used for release validation on DuckDB 1.5.6 (f386a6cf on DuckDB 1.5.4), not a revision locked by this package. A fresh installation may obtain a newer community build for the same engine and platform.
Validation for 1.6.1: 514 tests passed, 24 skipped on Node 20.19.5, 22.19.0, and 24.19.0. Linux native checks passed for DuckPGQ graph matching, shortest paths, PageRank, and Onager PageRank; an MCP stdio client initialized, listed 40 tools, and executed SQL. The lockfile audit reported no vulnerabilities on 2026-09-14.
Validation for the DuckDB 1.5.6 bump (2026-10-22, Linux x64): 564 tests passed, 26 skipped, 0 failed on Node 20.20.0, 22.22.0 and 24.19.0 (the DuckDB 1.5.4 baseline on the same commit: 564 passed, 26 skipped on Node 22.22.0); the engine sandbox tests pass with identical per-test results; the DuckPGQ capability suite passes 15/20 with results identical to 1.5.4; Onager 0.4.0 loaded and its pagerank, louvain, betweenness, dijkstra, adamic_adar and density queries passed. Other platforms were not natively validated.
See the release notes and publishing guide.
Installation
As MCP Server (Claude Desktop / Claude Code)
{
"mcpServers": {
"duckdb": {
"command": "npx",
"args": ["@seed-ship/duckdb-mcp-native"],
"env": {
"DUCKDB_MEMORY": "4GB",
"DUCKDB_THREADS": "4",
"MCP_SECURITY_MODE": "development"
}
}
}
}With S3/MinIO:
{
"mcpServers": {
"duckdb": {
"command": "npx",
"args": ["@seed-ship/duckdb-mcp-native"],
"env": {
"DUCKDB_MEMORY": "4GB",
"DUCKDB_THREADS": "4",
"MCP_SECURITY_MODE": "development",
"MINIO_PUBLIC_ENDPOINT": "https://s3.example.com",
"MINIO_ACCESS_KEY": "your-access-key",
"MINIO_SECRET_KEY": "your-secret-key",
"MINIO_REGION": "us-east-1",
"MINIO_USE_SSL": "true"
}
}
}
}Config file locations:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
As NPM Package
npm install @seed-ship/duckdb-mcp-nativeFor Development
git clone https://github.com/theseedship/duckdb_mcp_node
cd duckdb_mcp_node
npm install
npm run dev:server # Start MCP server
npm run inspector # Test with Inspector UI
npm test # Run testsMCP Tools
Database Operations
| Tool | Description |
| ---------------- | --------------------------------------- |
| query_duckdb | Execute SQL queries with optional LIMIT |
| list_tables | List tables in a schema |
| describe_table | Get table structure (columns, types) |
| load_csv | Load CSV files into DuckDB |
| load_parquet | Load Parquet files into DuckDB |
Federation
| Tool | Description |
| ----------------------- | ------------------------------ |
| attach_mcp | Connect to external MCP server |
| detach_mcp | Disconnect server |
| list_attached_servers | Show connections |
| list_mcp_resources | List remote resources |
| create_virtual_table | Create table from MCP resource |
| drop_virtual_table | Remove virtual table |
| list_virtual_tables | Show virtual tables |
| refresh_virtual_table | Update table data |
| query_hybrid | Query across local/remote data |
DuckLake-style Snapshots (ACID + Time Travel)
| Tool | Description |
| ---------------------- | ------------------------------------------ |
| ducklake.attach | Attach or create snapshot catalog |
| ducklake.snapshots | List, view, clone, or rollback snapshots |
| ducklake.time_travel | Query historical data at any point in time |
These tools are a self-contained emulation (catalog tables + Parquet on S3/MinIO) — they do not require, or use, the official
ducklakeextension. If you need true multi-reader/multi-writer lakehouse semantics, install the officialducklakeextension (DuckDB ≥ 1.5.2, PostgreSQL catalog recommended for concurrency) alongside this package.
MotherDuck Cloud
MotherDuck lists DuckDB clients up to 1.5.6 as supported (version lifecycle, checked 2026-10-22), which is the engine this package runs. The
motherduck.*tools have not been exercised against a live MotherDuck workspace on 1.5.6: check the lifecycle page for current ranges per region before relying on them.
| Tool | Description |
| ---------------------------- | --------------------------- |
| motherduck.attach | Connect to MotherDuck cloud |
| motherduck.detach | Disconnect |
| motherduck.status | Check connection and usage |
| motherduck.list_databases | List cloud databases |
| motherduck.create_database | Create cloud database |
| motherduck.query | Execute cloud queries |
| motherduck.share_table | Share local table to cloud |
| motherduck.import_table | Import cloud table locally |
Graph Algorithm Tools
8 MCP tools for graph analysis using iterative SQL with temp tables (no recursive CTEs — DuckPGQ workaround).
Tools
| Tool | Description |
| ------------------------ | -------------------------------------------------------------- |
| graph.pagerank | PageRank centrality with configurable damping/iterations |
| graph.eigenvector | Eigenvector centrality via power iteration |
| graph.community_detect | Label propagation community detection |
| graph.modularity | Modularity score Q for community quality |
| graph.weighted_path | Weighted paths: strongest, cheapest, or combined |
| graph.temporal_filter | Filter graph by time period, return stats |
| graph.compare_periods | Compare two periods (NEW/REMOVED/STRENGTHENED/WEAKENED/STABLE) |
| graph.export | Export as JSON, CSV (Gephi), D3, GraphML, or Parquet |
Usage
All tools share a common base schema:
import { graphToolHandlers } from '@seed-ship/duckdb-mcp-native/graph'
const result = await graphToolHandlers['graph.pagerank'](
{
node_table: 'vars',
edge_table: 'drives',
node_id_column: 'var_id',
source_column: 'from_var',
target_column: 'to_var',
weight_column: 'confidence',
iterations: 20,
damping: 0.85,
top_n: 10,
},
duckdb
)
// result.nodes = [{ node_id: 4, rank: 0.21 }, ...]Temporal Analysis
// Compare graph evolution across time periods
const changes = await graphToolHandlers['graph.compare_periods'](
{
node_table: 'vars',
edge_table: 'drives',
source_column: 'from_var',
target_column: 'to_var',
weight_column: 'confidence',
period_column: 'period',
period_a: '1993-2023',
period_b: '2020-2023',
},
duckdb
)
// changes.summary = { new_edges: 3, removed_edges: 5, strengthened: 2, ... }DuckPGQ Property Graph Support
SQL:2023 Property Graph queries — with automatic DuckPGQ installation from community repository.
Configuration
# Required for DuckPGQ
ENABLE_DUCKPGQ=true
ALLOW_UNSIGNED_EXTENSIONS=true
DUCKPGQ_SOURCE=community # Default, no custom URL neededCompatibility Matrix
| DuckDB Version | DuckPGQ Version | Fixed Paths | Bounded {n,m} | ANY SHORTEST | Kleene (alone) | Status | | ------------------- | --------------- | ----------- | ------------- | ------------ | -------------- | ----------------------------------------------------------------------------------------------------- | | 1.0.0 - 1.2.2 | Stable | ✅ | ✅ | ✅ | ✅ | Production Ready | | 1.4.1 | 7705c5c | ✅ | ✅ | ✅ | ❌ | Functional | | 1.5.0 | aec2e25 | ✅ | ✅ | ✅ | ❌ | Functional | | 1.5.1 – 1.5.3 | — | — | — | — | — | No working binary (1.5.1 SIGSEGVs on LOAD; 1.5.2/1.5.3 never built — cwida/duckpgq-extension#305) | | 1.5.4 | f386a6cf | ✅ | ✅ | ✅ | ❌ | Functional (previous) | | 1.5.5 | — | — | — | — | — | No binary found (HTTP 404 on linux_amd64 when checked 2026-10-22) | | 1.5.6 (current) | 61f5d082 | ✅ | ✅ | ✅ | ❌ | Functional |
1.5.1–1.5.3 gap: DuckPGQ had no working community binary for these (LOAD segfault). Fixed at 1.5.4 — that's why this package jumped DuckDB 1.5.0 → 1.5.4 directly, and then 1.5.4 → 1.5.6 (no DuckPGQ linux_amd64 binary was found for 1.5.5). See
docs/duckpgq/CAPABILITY_REPORT_1.5.md.
What Works (Validated 2026-10-22 — 61f5d082 on DuckDB 1.5.6; same results as f386a6cf on 1.5.4 and aec2e25 on 1.5.0)
✅ Native CSR Algorithms:
pagerank(graph, vertices, edges)— native PageRank table functionweakly_connected_component(graph, vertices, edges)— WCC table functionlocal_clustering_coefficient(graph, vertices, edges)— clustering table functionsummarize_property_graph('graph_name')— graph statisticsvertices(p)/edges(p)/path_length(p)— path extraction functions
✅ GEOMETRY + CRS Integration (NEW):
- Property graphs with
GEOMETRYvertex columns - Spatial functions (
ST_Distance,ST_AsText) inGRAPH_TABLE COLUMNS GEOMETRY('OGC:CRS84')CRS-typed vertex columns- PageRank/WCC/clustering on GEOMETRY vertex tables
✅ Graph Query Features:
- Property graph creation (VERTEX/EDGE TABLES)
- Pattern matching with
GRAPH_TABLE - Fixed-length paths (1-hop, 2-hop, N-hop)
- ANY SHORTEST path queries with
->*syntax - Bounded quantifiers
{n,m}with->{n,m}syntax - WHERE on edges in 1-hop patterns
- CTE wrapping GRAPH_TABLE (no segfault, #276/#294 fixed)
- Edge variable required:
[e:Label]
❌ Not Yet Available:
ALL SHORTEST— "Not implemented yet"CHEAPESTpath matching — not in parser- Standalone Kleene
->*/->+— blocked (safety: infinite results on cycles) - Anonymous edges
[:Label]— requires variable binding[e:Label] - Edge properties in bounded quantifiers
{n,m}— edge variable not accessible
Full capability report: docs/duckpgq/CAPABILITY_REPORT_1.5.md
Onager Graph Analytics (companion community extension)
Onager is a separate community extension (CogitatorTech, Rust + C++; 0.4.0 on DuckDB 1.5.6, 0.1.0-alpha.6 when first validated on 1.5.4 — pre-1.0, treat as alpha) that loads alongside DuckPGQ on DuckDB ≥ 1.5.4 and ships ~64 native graph functions (53 table + 11 scalar) — a NetworkX-class toolkit in SQL:
| Family (prefix) | Functions |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Centrality (ctr_) | pagerank, personalized_pagerank, betweenness, closeness, eigenvector, katz, harmonic, degree, voterank, laplacian, local_reaching |
| Community (cmm_) | louvain, label_prop, infomap, girvan_newman, spectral, components |
| Paths (pth_) | dijkstra, bellman_ford, floyd_warshall |
| Link prediction (lnk_) | adamic_adar, jaccard, common_neighbors, pref_attach, resource_alloc |
| Metrics (mtr_) | density, diameter, radius, transitivity, triangles, avg_clustering, avg_path_length, assortativity |
| Subgraphs (sub_) | ego_graph, induced, k_hop |
| Other | MST (kruskal/prim), BFS/DFS traversal, parallel variants (par_), approximation (apx_ max*clique/tsp/vertex_cover), generators (gen* erdos_renyi/barabasi_albert/watts_strogatz) |
Auto-loading (v1.6.0): set ENABLE_ONAGER=true (plus ALLOW_UNSIGNED_EXTENSIONS=true) and DuckDBService installs + loads Onager at startup — check service.onagerLoaded at runtime. Loading is graceful: if the binary is unavailable (offline, unsupported platform), the service continues without it. Or load manually:
INSTALL onager FROM community;
LOAD onager;
-- Native PageRank straight from an edge table — no property graph needed
SELECT * FROM onager_ctr_pagerank((SELECT src, dst FROM edges))
ORDER BY rank DESC LIMIT 10;
-- Louvain communities
SELECT * FROM onager_cmm_louvain((SELECT src, dst FROM edges));
-- Single-source shortest paths (named parameter required)
SELECT * FROM onager_pth_dijkstra((SELECT src, dst FROM edges), source = 1);Validated on DuckDB 1.5.4 (2026-07-03): pagerank, louvain, betweenness, dijkstra, adamic_adar, density all work. Re-validated on DuckDB 1.5.6 (2026-10-22, Onager 0.4.0): the same six functions work. Caveats (alpha):
- Node ids must be BIGINT (
column::BIGINTif needed) - Some functions bind only via named parameters (
source = 1, not positional) - Not built for
osx_amd64,windows_amd64_mingw, or WASM - API may change between alpha releases — evaluate before depending on it
Our 8 graph.* MCP tools remain iterative-SQL (portable, no extension dependency); Onager is a candidate native backend for them and adds net-new capabilities (betweenness, louvain, link prediction, ego/k-hop subgraphs).
Example Queries
-- Create property graph from existing tables
CREATE PROPERTY GRAPH social_network
VERTEX TABLES (Person)
EDGE TABLES (
Knows
SOURCE KEY (from_id) REFERENCES Person (id)
DESTINATION KEY (to_id) REFERENCES Person (id)
);
-- Direct connections (1-hop) - edge variable required
FROM GRAPH_TABLE (social_network
MATCH (p1:Person)-[k:Knows]->(p2:Person)
COLUMNS (p1.name AS person, p2.name AS friend)
);
-- Friends of friends (fixed 2-hop)
FROM GRAPH_TABLE (social_network
MATCH (p1:Person)-[k1:Knows]->(p2:Person)-[k2:Knows]->(p3:Person)
WHERE p1.id != p3.id
COLUMNS (p1.name AS person, p3.name AS friend_of_friend)
);
-- ANY SHORTEST path query
FROM GRAPH_TABLE (social_network
MATCH p = ANY SHORTEST (start:Person WHERE start.id = 1)-[k:Knows]->*(end:Person WHERE end.id = 10)
COLUMNS (start.name AS from_person, end.name AS to_person, path_length(p) AS hops)
);
-- Bounded quantifiers (1 to 3 hops)
FROM GRAPH_TABLE (social_network
MATCH (p1:Person)-[k:Knows]->{1,3}(p2:Person)
COLUMNS (p1.name AS person, p2.name AS connection)
);1.5.0 capabilities: docs/duckpgq/CAPABILITY_REPORT_1.5.md | Migration: docs/duckpgq/MIGRATE_DUCKDB_1.5.md
Process Mining Tools
Three specialized tools for analyzing workflow processes stored in Parquet files.
| Tool | Description |
| ------------------ | ------------------------------------------------------------- |
| process.describe | List and filter process summaries with confidence scores |
| process.similar | Find similar processes using vector embeddings (FLOAT[384]) |
| process.compose | Merge multiple processes into unified workflow with QA checks |
Embeddings & Similarity Search
- Validates embedding dimensions (configurable via
PROCESS_EMBEDDING_DIM, defaults to 384) - Automatic fallback to TypeScript L2 distance when DuckDB VSS is unavailable
- Results include
distance_sourcefield (duckdb_vssortypescript_l2) for observability
const results = await handlers['process.similar']({
signature_emb: [0.1, 0.2, ...], // 384-dimensional embedding
k: 5,
parquet_url: 's3://bucket/signatures.parquet',
})
// { matches: [{ doc_id: 'doc1', distance: 0.45, distance_source: 'duckdb_vss' }] }Process Composition
- Step normalization (lowercase + trim, handles "Login" vs "login")
- Conflict resolution via median order when multiple processes share a step
- Automatic edge remapping after step deduplication
- QA checks: detects orphan steps, cycles, and duplicate edges
const composed = await handlers['process.compose']({
doc_ids: ['doc1', 'doc2', 'doc3'],
steps_url: 's3://bucket/steps.parquet',
edges_url: 's3://bucket/edges.parquet',
})
// {
// success: true,
// steps: [...], // Deduplicated and normalized
// edges: [...], // Remapped edges
// merged_count: 5,
// qa: { orphan_steps: [], cycles: [], duplicate_edges: [], warnings: [] }
// }Configuration
PROCESS_SUMMARY_URL=s3://bucket/process_summary.parquet
PROCESS_STEPS_URL=s3://bucket/process_steps.parquet
PROCESS_EDGES_URL=s3://bucket/process_edges.parquet
PROCESS_SIGNATURE_URL=s3://bucket/process_signatures.parquet
PROCESS_EMBEDDING_DIM=384 # Match your embedding model (e.g., 1024 for text-embedding-3-large)Three Usage Modes
Mode 1: Standalone Server
DUCKDB_MEMORY=4GB DUCKDB_THREADS=4 npm run dev:server
# Or: npx @seed-ship/duckdb-mcp-nativeMode 2: Library Mode
Import tool handlers directly into your existing MCP server:
import { nativeToolHandlers, nativeToolDefinitions } from '@seed-ship/duckdb-mcp-native/lib'
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [...yourTools, ...nativeToolDefinitions],
}))
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params
if (name in nativeToolHandlers) {
return await nativeToolHandlers[name](args)
}
})Mode 3: Embedded Server
import { DuckDBMCPServer } from '@seed-ship/duckdb-mcp-native/server'
const server = new DuckDBMCPServer({
embeddedMode: true,
duckdbService: yourDuckDBInstance, // Optional
})
await server.start()
const handlers = server.getNativeHandlers()Virtual Filesystem
Query MCP resources directly in SQL with zero configuration:
-- Direct access with mcp:// URIs
SELECT * FROM 'mcp://weather-server/forecast.csv';
-- Join across servers
SELECT g.title, j.priority
FROM 'mcp://github/issues.json' g
JOIN 'mcp://jira/tickets.json' j ON g.id = j.github_id;
-- Glob patterns
SELECT COUNT(*) FROM 'mcp://*/logs/2024-*.csv' WHERE level = 'ERROR';Features: auto-format detection (CSV, JSON, Parquet, Arrow, Excel), intelligent caching, glob patterns.
Federation
// Attach servers
await handlers['attach_mcp']({
connectionString: 'stdio://github-mcp-server',
alias: 'github',
})
// Federated query
const result = await handlers['federate_query']({
sql: `
SELECT g.title, s.message
FROM 'mcp://github/issues.json' g
JOIN 'mcp://slack/messages.json' s ON g.id = s.issue_id
`,
})DuckLake (ACID + Time Travel)
// Attach catalog
await handlers['ducklake.attach']({
catalogName: 'analytics',
catalogLocation: 's3://data-lake/analytics',
format: 'DELTA',
enableTimeTravel: true,
})
// Time travel
const historical = await handlers['ducklake.time_travel']({
catalogName: 'analytics',
tableName: 'sales',
query: 'SELECT SUM(revenue) FROM sales',
timestamp: '2025-01-20T00:00:00Z',
})
// Snapshot management
await handlers['ducklake.snapshots']({
catalogName: 'analytics',
tableName: 'sales',
action: 'rollback',
version: 41,
})Security
Security is layered: an engine-level sandbox (the primary control, enforced inside DuckDB) plus HITL elicitation for destructive DML.
Modes
- development (default): no engine sandbox; destructive SQL is not gated
- production: engine sandbox on (
strict) + destructive SQL triggers HITL elicitation
Set via MCP_SECURITY_MODE=production. It is read directly — never inferred from NODE_ENV — so a process can set NODE_ENV=production without silently changing DuckDB's access policy. The value is case-insensitive and surrounding whitespace is ignored (Production, production\r); any other value (or the misspelled variable MCP_SECURITY_MODEL) is rejected at startup, because a typo would otherwise leave every protection off.
Engine sandbox (MCP_SANDBOX)
The DuckDB instance is hardened after trusted extensions and S3 credentials are provisioned, before it becomes ready for queries. This applies to library-mode consumers too. The level resolves from the constructor's sandbox option, then MCP_SANDBOX, then the mode default. Invalid explicit levels fail initialization.
| Level | Effect |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| off | No engine hardening (legacy behaviour). Default in development. Use only with trusted SQL. |
| strict | enable_external_access=false blocks external file access, including local files, HTTP and S3. Default in production. |
| no-local-fs | Explicit compatibility option: disables LocalFileSystem and HTTPFileSystem, but retains preconfigured S3 access. Not an SSRF boundary. |
In either hardened mode, extension auto-install/auto-load and persistent secrets are disabled, and configuration is locked (lock_configuration=true). Initialization fails closed if any required setting fails. INSTALL / LOAD / ATTACH are additionally refused by a lexical statement gate; this is defence in depth, and the engine settings above are the primary control. Credentials that DuckDB imports from the process environment (S3 and proxy settings) are reset before the lock; only the explicit s3Config secret is kept. Even in strict, DuckDB keeps access to its own temporary directory (.tmp under the working directory).
S3 compatibility requires trusted SQL and restricted network egress. no-local-fs retains network capabilities and must not be used as network isolation for untrusted SQL, even with configuration locking. Use strict when external access must be prohibited.
strict intentionally disables external imports/exports and S3. Both hardened modes reject mcp:// queries before VFS preprocessing: the current VFS imports through local cache files. Other disk-backed imports may also fail. In-memory SQL remains available; integrations needing external data must choose their policy explicitly.
The sandbox governs DuckDB operations, not arbitrary Node.js code, independently configured MCP connections, or the behavior of trusted native extensions loaded at startup. Applications embedding the library must explicitly enable MCP_SECURITY_MODE=production or sandbox: 'strict'; NODE_ENV=production alone does not enable protection. The policy is applied by this package's DuckDBService: applications supplying their own DuckDB service or connection must enforce their policy on that instance. Importing tool handlers or ComputeSession does not harden a caller-owned connection. Work done in Node rather than in DuckDB is outside the engine sandbox; json_to_parquet therefore no longer creates missing directories when a sandbox is active.
The keyword-based HITL gate below only covers selected destructive DML/DDL/DCL statements. It is not a complete SQL authorization boundary. File/network access is blocked by the production engine sandbox regardless of a HITL confirmation.
HITL Elicitation
In production mode, destructive operations (DROP, DELETE, ALTER, TRUNCATE, INSERT, UPDATE, GRANT, REVOKE) trigger a confirmation prompt via the MCP SDK's elicitation API:
| Scenario | Behavior | | ------------------------------------------ | ---------------------------- | | Client supports elicitation, user confirms | Query executes | | Client supports elicitation, user declines | Query blocked | | Client does not support elicitation | Query blocked (safe default) | | Elicitation times out or errors | Query blocked |
Configure timeout: MCP_ELICIT_TIMEOUT=30000 (ms, default 30s)
Architecture
src/
duckdb/ # DuckDB service with pooling
server/ # MCP server (32+ tools, HITL security)
client/ # MCP client for federation
federation/ # ResourceRegistry, ConnectionPool, QueryRouter
filesystem/ # Virtual Filesystem (mcp:// URIs)
protocol/ # Transport implementations (stdio, WS, TCP, HTTP)
tools/ # Graph, process, data helper, DuckLake, MotherDuck tools
context/ # Multi-tenant space isolation
monitoring/ # Performance metricsConfiguration
| Variable | Default | Description |
| --------------------------- | ---------------- | -------------------------------------------------------------------------------- |
| DUCKDB_MEMORY | 4GB | DuckDB memory limit |
| DUCKDB_THREADS | 4 | DuckDB thread count |
| MCP_SECURITY_MODE | development | development / production |
| MCP_SANDBOX | (mode-derived) | Engine sandbox: off / no-local-fs / strict (overrides the mode default) |
| MCP_ELICIT_TIMEOUT | 30000 | HITL elicitation timeout (ms) |
| MCP_MAX_QUERY_SIZE | 1000000 | Max SQL query size (chars) |
| MCP_CACHE_DIR | /tmp/mcp-cache | VFS cache directory |
| MCP_CACHE_TTL | 300000 | VFS cache TTL (ms) |
| ENABLE_DUCKPGQ | false | Enable DuckPGQ extension |
| ENABLE_ONAGER | false | Enable Onager graph analytics (opt-in, alpha; needs ALLOW_UNSIGNED_EXTENSIONS) |
| ONAGER_STRICT_MODE | false | Throw instead of warn if Onager fails to load |
| ALLOW_UNSIGNED_EXTENSIONS | false | Required for DuckPGQ / Onager |
| PROCESS_EMBEDDING_DIM | 384 | Embedding dimension for process mining |
Scripts
npm run dev:server # Start MCP server
npm run inspector # MCP Inspector UI
npm test # Run tests
npm run test:watch # TDD mode
npm run check:all # Typecheck + lint + format + tests
npm run lint:fix # Auto-fix lint issues
npm run format # Format code
npm run port:clean # Fix port issues
npm run inspector:reset # Reset stuck InspectorDocumentation
| Document | Description |
| ------------------------------------------------------ | ------------------------------------- |
| docs/CHANGELOG.md | Detailed changelog |
| docs/DEVELOPMENT.md | Development setup guide |
| docs/ARCHITECTURE.md | System architecture |
| docs/TRANSPORTS.md | Transport protocols + HITL flow |
| docs/FEDERATION_GUIDE.md | Federation documentation |
| docs/duckpgq/ | DuckPGQ findings and failure analysis |
| docs/roadmap/ | Roadmap and planning |
Requirements
- Node.js 20+
- For development: TypeScript 5.9 and Node.js 22 (also tested on Node.js 20 and 24)
License
MIT
