Supabase Lite MCP Server

Overview

The Supabase Lite MCP Server is a lightweight Model Context Protocol (MCP) server that provides essential Supabase database management commands. This focused implementation reduces token usage from ~14,800 to ~3,700 tokens by exposing only 8 core commands instead of the full 26.

Features

• 🚀 Minimal Token Usage: Only ~3,700 tokens vs ~14,800 for the full Supabase MCP
• 🎯 Essential Commands Only: 8 carefully selected database management commands
• 📦 Easy Installation: Automated setup script with environment validation
• 🔧 TypeScript: Full type safety and modern ES modules
• 🔐 Secure: Uses service role keys with proper environment variable handling
• 🛠️ Production Ready: Error handling, logging, and MCP protocol compliance

Quick Start

Automated Installation

# Clone the repository
git clone https://github.com/your-username/supabase-lite-mcp.git
cd supabase-lite-mcp

# Run the setup script
./setup.sh

The setup script will:

• Check Node.js version (requires v22+)
• Install dependencies
• Guide you through configuration
• Build the TypeScript code
• Optionally test the server

Manual Installation

1. Install dependencies:

   npm install
   

2. Configure environment:

   cp .env.example .env
   # Edit .env with your Supabase credentials
   

3. Build the project:

   npm run build
   

4. Test the server:

   npm run dev
   

Configuration

Environment Variables

Create a .env file with your Supabase credentials:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_PROJECT_REF=your-project-ref  # Optional

Get these from your Supabase dashboard:

• URL: Settings → API → Project URL
• Service Key: Settings → API → Service role key (NOT anon key!)
• Project Ref: Settings → General → Reference ID

Claude Integration

Add to your MCP configuration file (.mcp.json):

{
  "mcpServers": {
    "supabase-lite": {
      "command": "node",
      "args": ["path/to/supabase-lite-mcp/dist/index.js"],
      "env": {
        "SUPABASE_URL": "${SUPABASE_URL}",
        "SUPABASE_SERVICE_KEY": "${SUPABASE_SERVICE_KEY}"
      }
    }
  }
}

Or use npm link for global access:

cd supabase-lite-mcp
npm link

Then use "command": "supabase-lite-mcp" in your MCP config.

Available Commands

1. list_tables

Lists all tables in specified schemas.

• Use case: Discovering database structure
• Token cost: 457 tokens

2. list_extensions

Shows installed PostgreSQL extensions.

• Use case: Checking available database features
• Token cost: 413 tokens

3. list_migrations

Displays migration history.

• Use case: Tracking schema changes
• Token cost: 413 tokens

4. apply_migration

Applies DDL changes to the database.

• Use case: Creating tables, indexes, etc.
• Token cost: 485 tokens

5. execute_sql

Runs SQL queries for data operations.

• Use case: Querying and modifying data
• Token cost: 474 tokens

6. get_logs

Retrieves service logs from the last minute.

• Use case: Debugging issues
• Token cost: 516 tokens

7. get_advisors

Provides security and performance recommendations.

• Use case: Database optimization
• Token cost: 516 tokens

8. generate_typescript_types

Creates TypeScript interfaces from schema.

• Use case: Type-safe development
• Token cost: 417 tokens

Architecture

How It Works

The server implements the Model Context Protocol (MCP) to communicate with Claude:

Claude ↔️ MCP Protocol (stdio) ↔️ Server ↔️ Supabase API

Key Components

• MCP Server: Handles protocol communication via stdio
• Tool Registry: Defines available commands and their schemas
• Command Handlers: Execute Supabase operations
• Type Safety: Full TypeScript with strict typing
• Error Handling: Graceful error reporting in MCP format

Extending the Server

Adding New Commands

1. Add command to ALLOWED_COMMANDS in src/index.ts
2. Define tool schema in getToolDefinitions()
3. Add case in executeCommand() switch
4. Implement handler method

Example:

// 1. Add to ALLOWED_COMMANDS
const ALLOWED_COMMANDS = [
  // ... existing commands
  'custom_command'
] as const;

// 2. Add tool definition
tools.push({
  name: 'custom_command',
  description: 'My custom command',
  inputSchema: {
    type: 'object',
    properties: {
      param: { type: 'string' }
    }
  }
});

// 3. Add case in executeCommand
case 'custom_command':
  return await this.customCommand(args);

// 4. Implement handler
private async customCommand(args: any): Promise<any> {
  // Your implementation
  return {
    content: [{
      type: 'text',
      text: 'Result'
    }]
  };
}

Development

Scripts

• npm run build - Build TypeScript to JavaScript
• npm run dev - Run in development mode with hot reload
• npm start - Run production build
• npm run clean - Clean build artifacts

Project Structure

supabase-lite-mcp/
├── src/
│   └── index.ts        # Main server implementation
├── dist/              # Compiled JavaScript (generated)
├── .env               # Environment variables (create from .env.example)
├── .env.example       # Environment template
├── package.json       # Node.js configuration
├── tsconfig.json      # TypeScript configuration
├── setup.sh          # Installation script
└── README.md         # Documentation

Comparison with Full Supabase MCP

Feature	Full Supabase MCP	Supabase Lite MCP
Commands	26	8 (essential only)
Token Usage	~14,800	~3,700
Startup Time	~2s	<1s
Memory Usage	~50MB	~30MB
Focus	Complete platform	Database only

Security

• 🔒 Never commit .env files
• 🔑 Use service role keys carefully (full database access)
• 🔄 Rotate keys regularly
• 🌐 Consider network isolation for production

Troubleshooting

Common Issues

Server won't start:

• Check Node.js version: node --version (requires v22+)
• Verify .env file exists with valid credentials
• Run npm run build to compile TypeScript

Authentication errors:

• Ensure you're using the service role key, not anon key
• Check if the key has been regenerated in Supabase dashboard

Build errors:

• Run npm install to install dependencies
• Check TypeScript version: npx tsc --version

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Acknowledgments

Built with:

• Model Context Protocol SDK
• Supabase JavaScript Client
• TypeScript