← All projects

acp

Query databases with natural language from DuckDB. Works with Claude Code, Codex, and Gemini CLI.

GitHub Community Extensions Star

Query your database with plain English using the Agent Client Protocol (ACP). The extension integrates Claude Code to explore your schema and generate accurate SQL from natural language.

Installation

INSTALL acp FROM community;
LOAD acp;

Requirements

  • DuckDB 1.1.0 or later
  • Claude Code installed and configured

Usage

Ask questions in plain English:

CLAUDE what is the total revenue by product?
CLAUDE show me the top 10 customers by lifetime value
CLAUDE which products have declining sales month over month?

Or use as a table function

SELECT * FROM claude('compare Q1 vs Q2 revenue by region');

Configuration

See the generated SQL before execution

SET acp_show_sql = true;

Watch Claude's reasoning process

SET acp_show_messages = true;

Increase timeout for complex queries (default 300s)

SET acp_timeout = 600;

Allow mutations (use with caution)

SET acp_safe_mode = false;

Safety

By default, the extension runs in safe mode which blocks all mutation queries (INSERT, UPDATE, DELETE, DROP, etc.). Claude can only execute SELECT queries against your database.

How It Works

  1. You ask a question in natural language
  2. The extension spawns Claude Code with access to run SQL
  3. Claude explores your schema (tables, columns, sample data)
  4. Claude generates, tests, and refines the SQL query
  5. The final query is executed and results returned