@worthy-npm/dbarnacle-mcp

Model Context Protocol server exposing dBarnacle to LLM agents (Claude Code, Cursor, etc.).

Tools are intent-sized — they wrap the REST API with agent-friendly shapes (row caps, dry-run flags, stable error codes). Auth is a per-user API token; the MCP server inherits the token owner's permissions.

Install

npm i -g @worthy-npm/dbarnacle-mcp
# or run on demand without installing:
npx -y @worthy-npm/dbarnacle-mcp

Setup

1. Mint a token in dBarnacle: Settings → API tokens → Create. Save the dbat_… string (shown once).
2. Add the server to your agent's MCP config.

Cursor

~/.cursor/mcp.json (or .cursor/mcp.json per-workspace):

{
  "mcpServers": {
    "dbarnacle": {
      "command": "npx",
      "args": ["-y", "@worthy-npm/dbarnacle-mcp"],
      "env": {
        "DBARNACLE_URL": "https://your-dbarnacle.example.com/api",
        "DBARNACLE_TOKEN": "dbat_..."
      }
    }
  }
}

Claude Code

~/.claude/mcp.json:

{
  "mcpServers": {
    "dbarnacle": {
      "command": "npx",
      "args": ["-y", "@worthy-npm/dbarnacle-mcp"],
      "env": {
        "DBARNACLE_URL": "https://your-dbarnacle.example.com/api",
        "DBARNACLE_TOKEN": "dbat_..."
      }
    }
  }
}

Restart the agent. Tools named list_connections, run_query, get_dashboard_debug, etc., become available.

Env vars

| Var | Default | Notes | |---|---|---| | DBARNACLE_URL | http://localhost:3000/api | Base URL, including /api. | | DBARNACLE_TOKEN | (required) | dbat_… from the Settings panel. | | DBARNACLE_MCP_READONLY | 0 | Set to 1 to disable every mutating tool. | | DBARNACLE_MCP_ROW_CAP | 5000 | Applied to run_query results. |

Tool list (summary)

Read: list_connections, list_schemas, list_tables, describe_table, search_schema, run_query, explain_query, get_query_history, list_saved_queries, get_saved_query, list_charts, list_dashboards, get_dashboard, get_dashboard_debug (admin), list_alerts, get_alert.

Write: save_query, update_saved_query, delete_saved_query (dry-run), create_dashboard, delete_dashboard (dry-run), set_dashboard_filter, run_alert_now.

Safety rails

• Scoped tokens. The MCP server authenticates as the token owner; no admin-by-default shortcut.
• Readonly mode (DBARNACLE_MCP_READONLY=1) disables every mutating tool.
• Dry-run on destructive tools. delete_saved_query / delete_dashboard accept dryRun: true.
• Row caps on every query path. Default 5000; override per-call up to 5000.
• Stable error codes. Errors come back tagged with code values agents can pattern-match on (e.g. DASHBOARD_NOT_FOUND, QUERY_ERROR) — not free-text messages.

License

MIT