
che-duckdb-mcp
Swift-native DuckDB MCP + guidance Skill — dual-source docs (llms.txt + full) with TF-IDF search + fuzzy function matching, plus 6 local DB tools (14 total). Pinned duckdb-swift, real DuckDB error messages, SessionStart hook for version check.
- version
- 2.3.0
Install
/plugin install che-duckdb-mcp@psychquant-claude-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add PsychQuant/psychquant-claude-plugins.
Contents
Discovered from sourceSkills 1
che-duckdb-mcp — DuckDB Documentation & Local Database
14 tools split into documentation queries (8) and local database operations (6). The MCP runs the tools; this skill tells you when to use them vs alternatives.
Decision tree: which tool for which question?
"How do I use DuckDB function X?"
mcp__plugin_che-duckdb-mcp_duckdb__get_function_docs { function_name: "X" }
- Supports fuzzy matching:
read_csvs→read_csv,JSON_EXTRACT→json_extract - Prefer this over WebFetch — offline cached, Levenshtein-tolerant
- Prefer this over Grep — already indexed by the parser
"What's the DuckDB SQL syntax for X?"
mcp__plugin_che-duckdb-mcp_duckdb__get_sql_syntax { statement: "COPY" } # SELECT, INSERT, CREATE TABLE, etc.
- Use for SQL statements (SELECT, INSERT, CREATE, COPY, ATTACH, etc.)
- For general concepts ("window functions", "CTEs") use
search_docsinstead
"Search DuckDB docs for keyword X"
mcp__plugin_che-duckdb-mcp_duckdb__search_docs { query: "window functions", mode: "all", limit: 10 }
- Uses TF-IDF ranking (not substring match) — order matters, first result is usually best
mode:title(fastest),content,all(default)- Results include
sourcefield:llms.txt(concise) orduckdb-docs.md(full); llms.txt hits get 1.5× score bonus - Prefer this over WebFetch duckdb.org — offline, ranked, no network round trip
"Show me section X of the docs"
mcp__plugin_che-duckdb-mcp_duckdb__list_sections [{ level: 2 }] # browse structure
mcp__plugin_che-duckdb-mcp_duckdb__get_section { id: "..." } # fetch by anchor id
mcp__plugin_che-duckdb-mcp_duckdb__get_section { title: "COPY" } # fuzzy title match
"List all DuckDB functions"
mcp__plugin_che-duckdb-mcp_duckdb__list_functions
"My doc results look outdated"
mcp__plugin_che-duckdb-mcp_duckdb__refresh_docs # force re-download both llms.txt + duckdb-docs.md
mcp__plugin_che-duckdb-mcp_duckdb__get_doc_info # shows per-source lastUpdated, sectionCount, cachePath
Normally not needed — the MCP uses ETag/Last-Modified conditional HTTP caching, so it auto-refreshes when upstream changes.
Local database operations
"Connect to a .duckdb file"
mcp__plugin_che-duckdb-mcp_duckdb__db_connect { path: "/abs/path/to/file.duckdb", read_only: true }
pathomitted → in-memory database- Storage version check happens automatically before opening — incompatible files return a structured
storageVersionMismatcherror with upgrade suggestion - For remote / MotherDuck cloud databases, use
mcp-server-motherduckinstead (this MCP is local-only)
"Run a SELECT query"
mcp__plugin_che-duckdb-mcp_duckdb__db_query { sql: "SELECT ...", format: "markdown", limit: 1000 }
- Allowed: SELECT / WITH / SHOW / DESCRIBE / EXPLAIN / PRAGMA
- DDL / DML →
db_execute format:json(default),markdown(best for reading),csv- Default
limit: 1000— override explicitly if user needs full table
"Run CREATE / INSERT / UPDATE / DELETE"
mcp__plugin_che-duckdb-mcp_duckdb__db_execute { sql: "CREATE TABLE ... AS SELECT ..." }
"What tables are there? What's this table's schema?"
mcp__plugin_che-duckdb-mcp_duckdb__db_list_tables [{ include_views: true, schema: "main" }]
mcp__plugin_che-duckdb-mcp_duckdb__db_describe { table: "users" } # by name
mcp__plugin_che-duckdb-mcp_duckdb__db_describe { query: "SELECT a+b FROM t" } # result schema
"What version / state is the DB in?"
mcp__plugin_che-duckdb-mcp_duckdb__db_info
Returns DuckDB engine version, swiftBindingRevision (pinned), connection path, table count, read-only state.
When NOT to use this MCP
| User wants | Use instead |
|---|---|
| MotherDuck cloud database | mcp-server-motherduck |
| Remote / S3 .duckdb files | mcp-server-motherduck (supports s3://) |
| DuckDB installation / build guide | WebFetch duckdb.org/docs/installation |
| Very recent DuckDB release notes (hours old) | WebFetch github.com/duckdb/duckdb/releases |
| Writing SQL for other dialects (Postgres, SQLite) | Don't use this — DuckDB-specific |
Error messages to expect
Real DuckDB errors now surface cleanly (as of v2.0.0):
Binder Error: Referenced column "X" not found in FROM clause! Candidate bindings: "Y"— typo in column nameCatalog Error: Table with name X does not exist! Did you mean "Y"?— typo in table nameParser Error: syntax error at or near "X"— SQL syntax problemstorageVersionMismatch— file newer than current duckdb-swift
Previously these were all DuckDB.DatabaseError error N opaque strings — if you see that, the MCP binary is outdated and needs rebuild from the fix commit a8b5a88 or later.
Architecture notes
- MCP source: https://github.com/PsychQuant/che-duckdb-mcp
duckdb-swiftpinned to commitd90cf8d(DuckDB v1.5.0-dev)- Docs cache at
~/.cache/che-duckdb-mcp/(llms.txt + duckdb-docs.md + cache-meta.json) - Both documentation sources are merged into a single TF-IDF inverted index at startup
Hooks 1
MCP servers 1
Sponsors
Details
- Marketplace
- PsychQuant/psychquant-claude-plugins
- Source
- plugins/che-duckdb-mcp
- Author
- Che Cheng
- Category
- Development
More from PsychQuant/psychquant-claude-plugins
All 42- che-ical-mcpv1.7.0
- che-latex-mcpv0.7.0
- che-pixel-mcpv0.1.0
- che-svg-mcpv0.1.0
- che-telegram-mcpv1.0.0
- che-things-mcpv1.7.1
- che-word-mcpv1.17.0
- che-xcode-mcpv1.0.1
- che-zotero-mcpv1.0.2
- claude-config-guidev1.0.0
- claude-switchv1.0.0
- cli-toolsv1.0.0
- codex-batchv1.0.0
- docflowv1.0.1
- gifthubv1.2.1
- issue-driven-devv2.9.0
- lean-proverv1.1.0
- mcp-tccv0.1.2
- mcp-toolsv1.13.0
- parallel-ai-agentsv1.1.1
- perspective-writerv2.2.0
- plugin-toolsv1.8.0
- postgresql-guidev1.0.0
- r-docs-guidev1.0.0