Skip to main content
Glama
cowork-data-bridge

cowork-data-bridge

by robertodf99

cowork-data-bridge

An MCP server that lets Claude Cowork (or any MCP client) ask natural-language questions about a project's data. Each question is answered by Claude Code running headless (claude -p) with the project's repository as context (schema, domain docs) and a read-only database connection.

Why: a database connector alone does not know what the tables mean. The project's code and docs do. This bridge gives the answering agent both, and keeps each project's connection details out of version control.

How it works

server.mjs              MCP server (stdio) and a small CLI
lib.mjs                 project discovery, argument building, runner
projects/_example/      template for a project addon (committed)
projects/<name>/        your project addons (gitignored)
docs/adding-a-project.md

A project addon is a folder with these files:

File

Purpose

project.json

{ "description", "repo", "maxTurns"?, "timeoutMs"?, "allowedTools"? }. repo is the repository Claude Code reads (absolute path, or relative to the addon folder).

mcp.json

Database MCP server for Claude Code. Default: Postgres MCP Pro in restricted mode, with DATABASE_URI taken from the environment via ${DATABASE_URI}.

postgres-mcp-overrides.txt

Dependency overrides that let postgres-mcp==0.3.0 install today (see below). Only needed with the default mcp.json.

connect.sh

Executable. Opens a read-only connection, exports DATABASE_URI, runs the command it receives ("$@"), and cleans up when it exits.

CLAUDE.md

Required. Instructions for the analyst agent: read-only rules, where the schema lives, how to answer.

postgres-mcp==0.3.0 pins pglast==7.2.0, which is no longer on PyPI, and it breaks with mcp 2.x, which removed FastMCP. The overrides file pins compatible versions (pglast>=7.20,<8, mcp[cli]>=1.5,<2), and uvx --python 3.12 picks a Python that has wheels for them. Restricted mode still allows SELECT and blocks DROP, COMMIT; DELETE ... and SET default_transaction_read_only=off with these versions. The path is relative: Claude Code starts MCP servers in its working directory, which is the addon folder.

Tools exposed over MCP:

  • list_projects: name and description of every addon folder that has a project.json (folders starting with _ or . are skipped).

  • ask(project, question): runs, with the addon folder as working directory:

    <addon>/connect.sh claude -p <question> --output-format json
      --mcp-config <addon>/mcp.json --strict-mcp-config
      --append-system-prompt-file <addon>/CLAUDE.md --add-dir <repo>
      --allowedTools Read,Grep,Glob,<db tools> --tools Read,Grep,Glob,<db tools>
      --disallowedTools Bash,Write,Edit,NotebookEdit,WebFetch,WebSearch,Agent,<secret files>
      --permission-mode dontAsk --restricted --no-session-persistence --max-turns <n>

    and returns the answer text. <db tools> is allowedTools from project.json, or mcp__<server>__* for every server in mcp.json. <secret files> denies .env*, *.pem and *.key files in the repository and the addon folder (see Security notes). Failures (connect script error, non-zero exit, error result, unparsable output, timeout, cancellation) come back as MCP tool errors with the last 2 KB of stderr, with postgres:// URLs and IPv4 addresses redacted. On success, stderr lines starting with WARNING (for example a cleanup that failed) are appended to the answer under "Bridge warnings", redacted the same way. Questions for the same project run one at a time. When the client cancels a call (or its request times out and it sends a cancellation), the run is stopped and the next queued question starts. When the client sends a progress token, a progress notification is sent every 15 seconds.

Related MCP server: rbac-rag-assistant

Setup

Requirements: Node.js 20 or later, Claude Code installed and logged in (claude on the PATH), and uv for uvx if you use the default Postgres MCP server. Plus whatever your connect.sh needs (a cloud CLI, curl, a VPN...).

git clone <this repo> /path/to/cowork-data-bridge
cd /path/to/cowork-data-bridge
npm install
npm test

Add a project (see docs/adding-a-project.md), then check it from a terminal:

node server.mjs list
node server.mjs ask <project> "How many active users last week?"

Register in Claude Desktop / Cowork

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json) and restart Claude Desktop:

{
  "mcpServers": {
    "data-bridge": {
      "command": "/path/to/node",
      "args": ["/path/to/cowork-data-bridge/server.mjs"],
      "env": {
        "PATH": "/path/to/node-bin-dir:/path/to/claude-bin-dir:/path/to/uvx-bin-dir:/path/to/cloud-cli-bin-dir:/usr/bin:/bin"
      }
    }
  }
}

Use absolute paths. Apps started from the macOS Dock do not get your shell's PATH, so PATH must list every directory that holds a program the chain needs: node, claude, uvx, and anything connect.sh calls (a cloud CLI, curl, psql...). Find them with which node claude uvx curl.

Optional environment variables:

Variable

Default

Meaning

BRIDGE_PROJECTS_DIR

<repo>/projects

Folder that holds the project addons. Use it to keep addons outside this repository.

BRIDGE_CLAUDE_BIN

claude

Claude Code executable.

BRIDGE_TIMEOUT_MS

300000

Time limit per question. timeoutMs in project.json overrides it. Values above 2147483647 are capped.

When a question times out, is cancelled, or the server shuts down, the whole process group of that run gets SIGTERM, then SIGKILL 30 seconds later if anything is still running. A trap in connect.sh has that time to close the connection.

Security notes

Read-only is enforced in layers, none of them perfect on its own:

  1. connect.sh should open a read-only session (for example PGOPTIONS="-c default_transaction_read_only=on", a read-only database role, or a replica) and refuse to run if it cannot.

  2. The database MCP server runs in restricted mode (--access-mode=restricted for Postgres MCP Pro).

  3. Claude Code only gets Read, Grep, Glob and the database tools; shell, file editing, web and subagents are disallowed, and dontAsk denies anything not pre-approved.

  4. The addon's CLAUDE.md tells the analyst to run only SELECT.

What the analyst can read:

  • Files: only inside the addon folder and the project repository. --restricted confines Read, Grep and Glob to those two working directories, so files elsewhere on disk (cloud CLI token caches, SSH keys, other repositories) are refused. Inside them, .env*, *.pem and *.key files are denied for all three tools. Everything else in those two folders is readable, so keep other secrets out of them.

  • Database: whatever the database user can read.

  • Context: with --restricted, Claude Code ignores user, project and local settings files (including hooks, permission rules, env and apiKeyHelper) and does not load CLAUDE.md memory files. The analyst gets the addon's CLAUDE.md through --append-system-prompt-file. The bridge repository still has no root CLAUDE.md as a precaution.

Limits to be aware of:

  • Rules about personal data, secrets and message content are prompt instructions only. There is no column masking and no audit log, and answers go to the MCP client.

  • Output filtering is limited to redacting postgres:// URLs (and IPv4 addresses in stderr-derived text).

  • The analyst inherits the server's environment variables.

  • Questions use your Claude Code login and count towards its usage. Because settings files are ignored, authentication must come from the normal login (or ANTHROPIC_API_KEY in the environment), not from apiKeyHelper.

Known limits

  • Whether Claude Cowork can reach a local stdio MCP server registered in Claude Desktop is not confirmed. The server works with any MCP client that runs local stdio servers.

  • MCP clients have their own tool-call timeouts. A long question may be cut off by the client even though progress notifications are sent.

  • One question at a time per project; no memory between ask calls.

  • The per-project queue lives in one bridge process. Do not ask about the same project from the CLI while an MCP client (such as Claude Desktop) is also asking: two runs can interfere, for example one run's cleanup closing access the other still uses.

  • A connect script that opens temporary access (such as a firewall rule) can leave it open if its cleanup is cut short by the SIGKILL escalation, or if the run is killed while the access is being created. Write the script so the next run reclaims anything it left behind, and have it print a line starting with WARNING to stderr when cleanup fails so the answer shows it.

  • If the server is killed outright (SIGKILL), runs in progress are not stopped: they continue in their own process group until Claude Code finishes (bounded by --max-turns), and connect.sh cleans up then.

  • --max-turns and --append-system-prompt-file are accepted by Claude Code (verified with 2.1.326) but not listed in claude --help.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables natural-language querying of Postgres and MongoDB databases in read-only mode, with PII masking and row/timeout guardrails, from any MCP client.
      -
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to ask plain-language questions and receive answers grounded only in documents the configured role is cleared to read, with the same access-controlled tools available across any client.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to ask bilingual data questions, inspect database tables and schemas, and execute validated read-only SQL through exposed tools.
      MIT