duckcoop

MCP server that lets an LLM client run sandboxed, read-only SQL (via DuckDB) against CSV/Parquet/JSON files under a directory you choose. Like a duck, it only gets to paddle around the pen you build for it.

Usage

npm run build
node dist/cli.js /path/to/sandbox-root

Optional flags: --scratch-dir <path> (defaults to a temp directory), --max-temp-size <size> (defaults to 4GB).

Exposes two tools: query (SELECT / CREATE TEMP VIEW / CREATE TEMP TABLE only) and list_files (data files under the sandbox root). See docs/adr/ for the security model.

Registering with an MCP client

Claude Code

claude mcp add duckcoop node /absolute/path/to/duckcoop/dist/cli.js /absolute/path/to/sandbox-root

Claude Desktop

Add an entry to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "duckcoop": {
      "command": "node",
      "args": [
        "/absolute/path/to/duckcoop/dist/cli.js",
        "/absolute/path/to/sandbox-root"
      ]
    }
  }
}

Restart Claude Desktop for the change to take effect.

Querying files you drag-and-drop into a chat: Claude Desktop doesn't save chat attachments to a path duckcoop can see. Files dropped in a Local Agent Mode session instead land under ~/Library/Application Support/Claude/local-agent-mode-sessions/<account-id>/<session-id>/local_<id>/outputs/. Point the sandbox root at the stable parent directory, ~/Library/Application Support/Claude/local-agent-mode-sessions, so newly created session folders are covered without editing the config again:

{
  "mcpServers": {
    "duckcoop": {
      "command": "node",
      "args": [
        "/absolute/path/to/duckcoop/dist/cli.js",
        "/Users/<you>/Library/Application Support/Claude/local-agent-mode-sessions"
      ]
    }
  }
}