Search Shortcut cmd + k | ctrl + k
acp
Downloads 302this week
GitHub stars 7
Extension repository on GitHub
Extension descriptor (YAML)

Natural language to SQL via Claude Code using the Agent Client Protocol (ACP). Query your data with plain English via CLAUDE statements or the claude() table function.

Maintainer(s): sidequery

Installing and Loading 

INSTALL acp FROM community;
LOAD acp;

Example 

-- Load the extension
LOAD 'acp';

-- Create sample data
CREATE TABLE sales (id INT, product VARCHAR, amount DECIMAL, sale_date DATE);
INSERT INTO sales VALUES
    (1, 'Widget', 99.99, '2024-01-15'),
    (2, 'Gadget', 149.99, '2024-01-16'),
    (3, 'Widget', 99.99, '2024-01-17');

-- Query with natural language (statement syntax)
CLAUDE what is the total revenue by product?

-- Or use the table function
SELECT * FROM claude('which product has the highest average sale amount?');

About acp

The ACP extension enables natural language to SQL translation using the Agent Client Protocol (ACP). Write queries in plain English and let an AI agent explore your schema and generate accurate SQL.

Two Query Interfaces:

  • Statement syntax: CLAUDE show me the top 10 customers by revenue
  • Table function: SELECT * FROM claude('what products sold the most last month?')

How It Works:

  1. The extension intercepts natural language queries
  2. An embedded MCP server provides schema exploration tools
  3. The agent (Claude Code) discovers tables, columns, and data patterns
  4. SQL is generated, tested, and executed against your database

Configuration Settings:

  • acp_agent: Agent command (default: claude-code)
  • acp_safe_mode: Block mutation queries (default: true)
  • acp_debug: Enable debug output (default: false)
  • acp_timeout: Timeout in seconds (default: 300)

Safety Features:

  • Safe mode blocks INSERT, UPDATE, DELETE by default
  • Agent has access only to SQL execution, no external tools
  • Configurable timeout prevents runaway queries

Requirements:

  • DuckDB 1.1.0+
  • bun or Node.js (for the agent runtime)
  • Claude Code with Anthropic API credentials or a Claude Pro/Max account

Added Functions

function_name function_type description comment examples
claude table NULL NULL  

Added Settings

name description input_type scope aliases
acp_agent ACP agent to use: 'claude-code' or path to binary VARCHAR GLOBAL []
acp_debug Enable debug output to stderr BOOLEAN GLOBAL []
acp_safe_mode Block mutation queries (INSERT, UPDATE, DELETE, DROP, etc.) BOOLEAN GLOBAL []
acp_show_datasources Show datasources and calculations from agent BOOLEAN GLOBAL []
acp_show_messages Show agent messages/thinking to stderr BOOLEAN GLOBAL []
acp_show_sql Show generated SQL before executing BOOLEAN GLOBAL []
acp_show_summary Show analysis summary from agent BOOLEAN GLOBAL []
acp_timeout Timeout in seconds for agent session (0 = no timeout) INTEGER GLOBAL []