cxdb-mcp

A Model Context Protocol (MCP) server that gives Claude direct, read-only access to the cxdb PostgreSQL database. This lets you query production data in plain English — no SQL knowledge required — straight from Claude Code or the Claude desktop app.

---

Why does this exist?

Normally, getting data out of cxdb means opening a database client, writing SQL, and sharing results manually. This tool removes that friction.

With cxdb-mcp connected to Claude, you can ask things like:

• "How many loads were posted last week?"
• "Give me the details of the user with email x@example.com"
• "What tables relate to companies and subscriptions?"

Claude handles the SQL, runs it safely in a read-only transaction, and returns the results directly in your conversation. No write access is possible.

---

Tools available

Tool	What it does
query	Runs a SELECT or WITH query against cxdb
list_tables	Lists all tables in the database
describe_table	Shows columns and types for a given table

---

Prerequisites

• Node.js v18 or higher
• Claude Code (CLI or desktop app)
• Database credentials for cxdb — ask your team lead

---

Setup

1. Clone the repo

git clone https://github.com/uvan1999/cxdb-mcp.git
cd cxdb-mcp

2. Install dependencies

npm install

3. Configure your credentials

Copy the example env file and fill in your own database details:

cp .env.example .env

Open .env and set the values:

DB_HOST=your-db-host
DB_PORT=5432
DB_NAME=your-db-name
DB_USER=your-db-user
DB_PASSWORD=your-db-password

Never commit .env to git. It is already listed in .gitignore.

4. Register the MCP server with Claude Code

Open your Claude Code settings file at ~/.claude/settings.json and add the following inside the mcpServers object:

"cxdb": {
  "command": "node",
  "args": ["/absolute/path/to/cxdb-mcp/index.js"],
  "env": {
    "DB_HOST": "your-db-host",
    "DB_PORT": "5432",
    "DB_NAME": "your-db-name",
    "DB_USER": "your-db-user",
    "DB_PASSWORD": "your-db-password"
  }
}

Replace /absolute/path/to/cxdb-mcp/ with the actual path where you cloned the repo (e.g. /Users/yourname/projects/cxdb-mcp).

The credentials go in settings.json rather than the .env file when using Claude Code, because Claude Code passes them as environment variables directly to the server process.

5. Restart Claude Code

After saving settings.json, restart Claude Code for the MCP server to be picked up.

---

Verify it's working

In Claude Code, ask:

"List the tables in cxdb"

Claude should respond with a list of all tables — no SQL required.

---

Security notes

• All queries run inside a read-only transaction (BEGIN READ ONLY). Writes, deletes, and schema changes are not possible.
• Only SELECT and WITH statements are accepted. Any other statement type is rejected before it reaches the database.
• Your credentials are never stored in this repository. The .gitignore excludes .env and the source code contains no hardcoded values.