Tablr MCP Server

MCP server for managing PostgreSQL databases with natural language through AI assistants like Claude, Cursor, and VS Code.

Quick Start

Prerequisites

• Node.js 18.0.0+
• PostgreSQL database
• Tablr API key (Get one here)

Installation

npm install -g tablr-mcp

Configuration

Create a .env file:

TABLR_API_KEY=tb_12345678_your_api_key_here
PG_CONNECTION_STRING=postgresql://username:password@hostname:port/database

MCP Setup

Option A: Using .env file (Recommended)

{
  "mcpServers": {
    "tablr": {
      "command": "tablr-mcp",
      "args": ["/absolute/path/to/your/.env"]
    }
  }
}

Option B: Auto-detect .env

{
  "mcpServers": {
    "tablr": {
      "command": "tablr-mcp"
    }
  }
}

Option C: Direct environment variables

{
  "mcpServers": {
    "tablr": {
      "command": "tablr-mcp",
      "env": {
        "TABLR_API_KEY": "your-api-key",
        "PG_CONNECTION_STRING": "your-connection-string"
      }
    }
  }
}

Usage

Start using natural language commands:

"Show me all tables"
"Create a users table with email, name, and created_at columns"
"Insert a user with email '[email protected]'"
"Add an index on the email column"

Available Tools (15 total)

Database Discovery

1. list_tables - List all database tables
2. get_table_schema - Get table structure and constraints

Schema Management

3. create_table - Create new tables with columns/constraints
4. alter_table - Modify table structures
5. alter_column - Change column properties
6. rename_table - Rename existing tables
7. drop_table - Remove tables

Data Operations

8. query_records - Query and filter data
9. insert_records - Insert new data
10. update_records - Update existing records
11. delete_records - Delete records with conditions

Index Management

12. add_index - Create database indexes
13. drop_index - Remove database indexes

Constraint Management

14. add_constraint - Add table constraints

Advanced Tools

15. execute_sql - Run custom SQL queries

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | TABLR_API_KEY | Yes | Tablr API key for usage tracking | | PG_CONNECTION_STRING | Yes | PostgreSQL connection string |

Usage Examples

Table Management

"Create a posts table with title (varchar), content (text), and published_at (timestamp)"
"Rename the posts table to articles"
"Add a unique constraint on the email column"

Data Operations

"Insert: email='[email protected]', name='John', active=true"
"Show users created in the last 7 days"
"Update user 123 to set email_verified=true"

Schema Changes

"Add a nullable bio column to users table"
"Create an index on the created_at column"
"Drop the old_column from users table"

Architecture

AI Assistant ──► MCP Server ──► PostgreSQL
    │              │
    └──────────────► Tablr API (usage tracking)

• MCP Server: Handles AI communication and tool execution
• PostgreSQL Client: Direct database operations
• Usage Tracker: Sends metrics to Tablr for billing
• Schema Discovery: Auto-detects tables via information_schema

Security

• Local Processing: Database operations run on your machine
• Secure Credentials: PostgreSQL credentials stay local
• Parameterized Queries: SQL injection protection
• Environment Files: Store secrets in .env files, never commit to git

Troubleshooting

Connection Issues

• Verify PG_CONNECTION_STRING format
• Check database accessibility and permissions
• Ensure PostgreSQL is running

Authentication Problems

• Validate TABLR_API_KEY format (starts with tb_)
• Check API key hasn't expired
• Verify environment variables are loaded

Debug Mode

npm start -- --debug

Development

git clone https://github.com/yourusername/tablr-mcp.git
cd tablr-mcp
npm install
npm run build
npm start

Support

• GitHub Issues
• Tablr Dashboard

License

MIT License - see LICENSE file for details.