Content
# 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
```bash
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
```bash
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`):
```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:
```json
{
"mcpServers": {
"duckcoop": {
"command": "node",
"args": [
"/absolute/path/to/duckcoop/dist/cli.js",
"/Users/<you>/Library/Application Support/Claude/local-agent-mode-sessions"
]
}
}
}
```
