Claude CodeのDuckDBプラグインでCSVやParquetをその場で読む
DuckDB公式のduckdb-skillsプラグインは、read-fileとqueryでCSV・Parquetを読み、attach-dbでDB状態を引き継ぎます。入れ方、6つのskill、state.sqlの扱いをまとめます。
duckdb-skillsは、DuckDBのチームが配布するClaude Code用プラグインです。CSV・Parquet・JSONなどのデータファイルを、DBを用意せずにその場で読み、SQLで集計するための6つのskillが入っています。マーケットプレイスの掲載元はDuckDB Foundationです。ここでは入れ方、各skillの役割、状態ファイルstate.sqlの扱い、使うときの注意を順に見ていきます。
duckdb-skillsは何を足すプラグインか
プラグインが足すのは、DuckDBを呼び出すskillです。MCPサーバーではありません。READMEの前提条件には「DuckDB CLIが必要」とあり、未導入ならプラグイン側がinstall-duckdbで入れるよう案内します。つまり実体は、手元のDuckDB CLIをClaude Codeに正しく使わせるための手順書の束です。
skillは次の6つです。
| skill | 役割 |
|---|---|
read-file | 役割CSV・Parquet・JSON・Excelなどを読み、列やスキーマを調べる |
query | 役割SQLまたは自然言語の質問を実行する |
attach-db | 役割DuckDBのデータベースファイルを接続し、構造を調べる |
duckdb-docs | 役割DuckDBとDuckLakeのドキュメント・ブログを検索する |
read-memories | 役割過去のClaude Codeセッションログを検索する |
install-duckdb | 役割DuckDB拡張の導入と更新、CLIの版確認 |
呼び出しは/duckdb-skills:<skill名>の形です。プラグイン名が前に付くので、他のプラグインのskillと名前がぶつかりません。
MCP経由でDuckDBやMotherDuckに繋ぐ方法はDuckDB / MotherDuck MCPサーバーの接続手順が扱っています。サーバーを常駐させて接続先を切り替えたいならMCP、手元のファイルを数回読みたいだけならこのプラグインが軽い選択肢です。
インストール手順
READMEは2通りの経路を示しています。公式マーケットプレイスの検索画面(Discoverタブ)経由は「coming soon」と書かれ、GitHubから入れる方法が「available now」の扱いです。一方、claude.comのマーケットプレイスにはduckdb-skillsのページがあり、掲載元と導入数(1,188)が表示されています。READMEの記述より掲載が先に進んでいる可能性があるため、画面に出るかどうかはお使いの環境で確かめてください。
GitHubから入れる場合は、Claude Codeのセッション内で次を実行します。
/plugin marketplace add duckdb/duckdb-skills
/plugin install duckdb-skills@duckdb-skills1行目でリポジトリをマーケットプレイスとして登録し、2行目でプラグインを入れます。以降のセッションで/duckdb-skills:<skill名>が使えるようになります。公式ドキュメントでは、/plugin installはセッション内では即座に入れず、プラグインの詳細パネルを開いてスコープを選ばせると説明されています。入れた直後に反映されない場合は/reload-pluginsで読み込み直せます。
更新はマーケットプレイスを先に更新してから、プラグインを更新します。
/plugin marketplace update duckdb-skills
/plugin update duckdb-skills@duckdb-skills公式マーケットプレイスの掲載ページには、Claude Codeボタンが用意されています。公式ドキュメントによると、このボタンはclaude plugin install <name>@claude-plugins-officialの形のコマンドをコピーします。ボタンのコピー結果をそのまま使うのが確実です。
ローカルのクローンで試すなら、リポジトリをcloneしてclaude --plugin-dir .で起動します。ディスクから読み込むので、skills/*/SKILL.mdを編集すると新しい会話から反映されます。skillの挙動を自分の用途に合わせて直したいときに向きます。
read-fileとqueryでファイルをその場で読む
最初に使うのはread-fileです。拡張子から形式を自動判定します。READMEによると、内部ではread_anyという組み込みのテーブルマクロを使います。対応はCSV・JSON・Parquet・Avro・Excel・空間データ・SQLite・Jupyterノートブックなどで、ローカルに加えてS3・GCS・Azure・HTTPSのリモートも読めます。
/duckdb-skills:read-file variants.parquet what columns does it have?
/duckdb-skills:read-file https://example.com/data.csv how many rows?ファイルの後ろに質問を続けられるので、「列は何か」「何行あるか」をそのまま聞けます。深掘りが必要になれば、read-fileはqueryを勧める作りです。
queryはSQLと自然言語のどちらも受け付けます。DuckDBの「Friendly SQL」方言で書かれ、FROMから始めるSQLも通ります。
/duckdb-skills:query FROM 'exports.csv' WHERE amount > 100
/duckdb-skills:query "what are the top 5 customers by revenue?"ファイルに直接問い合わせるアドホックな使い方と、後述のattach-dbで接続済みのDBに問い合わせる使い方の両方に対応します。
attach-dbで接続状態を引き継ぐ
何度も同じDBを触るなら、attach-dbで接続します。DuckDBのファイルを指定すると、テーブル・列・行数を調べたうえで、接続情報をstate.sqlというSQLファイルに書き出します。
/duckdb-skills:attach-db my_analytics.duckdbREADMEによると、state.sqlはプロジェクト内の.duckdb-skills/state.sqlか、ホーム配下の~/.duckdb-skills/<project>/state.sqlのどちらかに置きます。最初に必要になった時点で保存先を聞かれます。attach-dbを再実行すると、複数のDBを追記できます。
このファイルは単なるSQLで、ATTACH・USE・LOADの各文のほか、シークレットやマクロも入ります。追記専用で冪等に書かれ、どのskillもduckdb -init state.sqlでセッションを復元します。read-fileが設定したシークレットやマクロをqueryが使い回せるのは、この共有のおかげです。
保存先の選び方は、リポジトリをどう扱うかで決まります。プロジェクト内に置くとデータの接続情報がリポジトリの隣に並びます。READMEもgitignoreを任意の選択肢として挙げています。リモートストレージのシークレットが入りうるため、コミット対象にするかは明示的に決めておきたいところです。リポジトリを汚したくない場合はホーム配下を選べます。
duckdb-docs・read-memories・install-duckdb
残りの3つは補助的な位置づけです。
duckdb-docsは、DuckDBとDuckLakeのドキュメントやブログを全文検索します。ホストされた検索インデックスにHTTPSで問い合わせるため、ローカルの準備は要りません。オフライン用にインデックスをキャッシュする選択肢もあります。queryやread-fileはエラーが出たとき、このduckdb-docsで自動的に原因を調べます。
read-memoriesは、過去のセッションログから決定事項や未完了のTODOを探します。大きな結果は一時的なDuckDBファイルに移し、そこから掘り下げます。--hereを付けた例がREADMEにあります。
install-duckdbは拡張の導入用です。spatialやhttpfsのような名前を並べて渡せます。gcs@communityのように名前@リポジトリで、コミュニティ拡張も指定できます。--updateを付けると、DuckDB CLIが最新の安定版かも確認します。
CLAUDE.mdに添えておく運用メモ
skillは必要な場面でClaudeが呼び出しますが、プロジェクトにデータの置き場所があるなら、先に伝えておくと迷いが減ります。次は例えば、データ分析用のリポジトリに置く断片です(skillの仕様ではなく、運用の一案です)。
## データ分析
- 生データは `data/` にあり、CSVとParquetが混在する
- ファイルの中身を調べるときは `/duckdb-skills:read-file` を先に使う
- 集計結果を報告するときは、実行したSQLも一緒に示す最後の1行が実用上は効きます。DuckDBに実際に投げたSQLが手元に残るので、数字の根拠を後から確かめられます。
プラグインとMCPのどちらで繋ぐか
DuckDBをClaude Codeから使う経路は、このプラグインとMCPサーバーの2つがあります。どちらもDuckDBを動かす点は同じで、違いは常駐するかどうかです。
| 観点 | duckdb-skillsプラグイン | MCPサーバー |
|---|---|---|
| 仕組み | duckdb-skillsプラグインskillがDuckDB CLIを呼び出す | MCPサーバーサーバーがツールを提供する |
| 接続状態 | duckdb-skillsプラグインstate.sqlに書き出して復元する | MCPサーバーサーバーの起動設定と接続パラメータで決まる |
| 向く場面 | duckdb-skillsプラグイン手元のファイルを読んで集計する | MCPサーバー接続先を切り替えながら繰り返し使う |
| 事前準備 | duckdb-skillsプラグインDuckDB CLI(未導入ならskillが案内) | MCPサーバーサーバーの起動設定 |
プラグインの状態はSQLファイルに残るため、中身を開いて確かめられます。接続情報を目で追えるのは、分析の再現性を保ちたい場面で扱いやすい点です。
初回の流れを通しで追う
手元にsales.csvとvariants.parquetがあるとして、初めて触る流れを並べます。
/plugin marketplace add duckdb/duckdb-skillsと/plugin install duckdb-skills@duckdb-skillsで入れる/duckdb-skills:read-file sales.csv what columns does it have?で列を確かめる/duckdb-skills:query FROM 'sales.csv' LIMIT 10で中身を数行見る- 結果を繰り返し使うと分かったら、
/duckdb-skills:attach-dbでDBファイルを接続する
2と3はstate.sqlを作らなくても進みます。READMEが「状態が必要になった時点で保存先を聞かれる」と述べているのは、この段階的な使い方に沿っています。大きなファイルを何度も読むなら、read-fileがDBへの永続化としてattach-dbを勧めます。
自然言語で質問する場合も、返ってきた数字を鵜呑みにせず、実行されたSQLを見る習慣が役立ちます。列名の取り違えや、集計の条件の読み違えは、SQLを見れば気づけます。
つまずきやすい点
プラットフォーム対応を確認しておく必要があります。READMEは、macOSとLinuxでテスト済みで、Windowsは完全対応ではないと述べています。シェルコマンドやパスの扱いが期待どおりに動かない場合があるそうです。Windowsで試すなら、小さなファイルでread-fileが通るかを先に確かめるとよいでしょう。
リモートのファイルを読むときは、シークレットの扱いに気を付けてください。S3などの認証情報はセッション状態に入りうるので、state.sqlの保存先とコミット方針を先に決めておくと安全です。
skillが動かないときは、まずDuckDB CLIの有無を疑います。duckdb --versionで確かめ、無ければ/duckdb-skills:install-duckdbで入れます。DuckDB固有の不具合を報告するときは、READMEがduckdb --versionの出力と完全なエラー文を添えるよう求めています。
プラグインの一覧や有効状態を調べたいときはplugin listのJSON出力が使えます。マーケットプレイスの仕組み全体はプラグインとマーケットプレイスの解説にあります。同じ公式プラグイン型の導入例にはLogfireプラグインもあります。
まとめ
duckdb-skillsは、DuckDB CLIをClaude Codeから安全に使うための6つのskillです。ファイルを読むだけならread-fileとqueryの2つで足ります。同じDBを繰り返し触るならattach-dbでstate.sqlを作り、保存先とコミット方針を最初に決めます。サーバー常駐や接続先の切り替えが要る場合だけ、MCPに移る判断になります。