Explore your database with Claude

Get started

1. Install the DuckDB CLI

   Claude talks to your database through the DuckDB CLI. On macOS, install it with Homebrew. Other platforms: see the DuckDB installation guide.

   brew install duckdb

2. Create an init.sql file

   Put it next to selfsync-db.duckdb and replace the paths with the absolute paths of your database and of selfsync-report.html. READ_ONLY guarantees Claude cannot modify your data. mcp_publish_query shares the report with Claude as an MCP resource.

   INSTALL duckdb_mcp FROM community;
   LOAD duckdb_mcp;
   
   ATTACH '/absolute/path/to/selfsync-db.duckdb' AS selfsync (READ_ONLY);
   USE selfsync;
   
   -- Publishes the report as an MCP resource, to give Claude the full context
   PRAGMA mcp_publish_query(
       'SELECT content FROM read_text(''/absolute/path/to/selfsync-report.html'')',
       'selfsync://report',
       'text',
       0
   );
   
   PRAGMA mcp_server_start('stdio');

3. Register the server in Claude Desktop

   Open Settings → Developer → Edit Config, add the server to claude_desktop_config.json, then restart Claude. If Claude cannot find duckdb, use the full path given by which duckdb (e.g. /opt/homebrew/bin/duckdb).

   {
     "mcpServers": {
       "SelfSync": {
         "command": "duckdb",
         "args": ["-init", "/absolute/path/to/init.sql"]
       }
     }
   }

4. Or register it in Claude Code

   Using Claude Code instead? Run this once in your terminal.

   claude mcp add selfsync -- duckdb -init /absolute/path/to/init.sql

5. Attach the report

   The report documents every table, the naming conventions and queries already run on your data: the best context Claude can get. Claude does not read resources on its own: attach it at the beginning of a conversation. In Claude Desktop, click + and pick it from the SelfSync server. In Claude Code, type @selfsync:selfsync://report in your message. If Claude finds it empty, check the report path in init.sql.

6. Ask away

   Start with “Using the SelfSync database, how many kilometres did I run each year?”, then “Is my average heart rate on easy runs going down over time?” or “Find my longest ride and describe it: distance, climbing, power.”

Good to know

• Your database stays on your computer. Claude only sees the results of the queries it runs, inside your conversation.
• Mention “the SelfSync database” in your first question so Claude knows which tool to use.
• Ask Claude to show the SQL it ran: you can reuse it in any other tool on this page.

Other tools

• DuckDB UI
• TablePlus
• DBeaver
• DuckDB CLI
• Harlequin
• Python
• R
• JavaScript

Wondering what a table or a column holds? Browse the FIT file reference.