trackmcp
Back to directory
vivek100

supaMCPBuilder

View on GitHub

SupaMCP Server

11 stars TypeScriptOthers Updated Nov 1, 2025

Documentation

SupaMCPBuilder

A runtime-configurable MCP (Model Context Protocol) server for Supabase databases with inline JSON configuration support. Build dynamic tools for your Supabase database without writing code!

Features

  • 🚀 Zero Configuration: Works out of the box with any Supabase project
  • 🔧 Runtime Configurable: Define tools using JSON configuration
  • 🔐 Built-in Authentication: Automatic JWT token refresh and session management
  • 📊 Dynamic Tool Generation: Create custom database operations via JSON
  • 🎯 Template Support: Use Jinja2-style templates in your configurations
  • 🔄 Base64 Support: Handle complex JSON configurations safely

Quick Start

Using with npx (Recommended)

bash
npx supamcpbuilder --url YOUR_SUPABASE_URL --anon-key YOUR_ANON_KEY --email YOUR_EMAIL --password YOUR_PASSWORD --tools-json-base64 BASE64_ENCODED_TOOLS

Installation

bash
npm install -g supamcpbuilder

Configuration Options

Basic Usage

bash
supamcpbuilder \
  --url "https://your-project.supabase.co" \
  --anon-key "your-anon-key" \
  --email "your-email@example.com" \
  --password "your-password"

With JSON Configuration File

bash
supamcpbuilder \
  --url "https://your-project.supabase.co" \
  --anon-key "your-anon-key" \
  --email "your-email@example.com" \
  --password "your-password" \
  --config-path "./tools-config.json"

With Base64 Encoded Tools

bash
supamcpbuilder \
  --url "https://your-project.supabase.co" \
  --anon-key "your-anon-key" \
  --email "your-email@example.com" \
  --password "your-password" \
  --tools-json-base64 "W3sibmFtZSI6Imxpc3QtdXNlcnMiLCJkZXNjcmlwdGlvbiI6Ikxpc3QgYWxsIHVzZXJzIn1d"

Tool Configuration Format

Basic Tool Structure

json
[
  {
    "name": "list-users",
    "description": "List all users from the users table",
    "parameters": {
      "type": "object",
      "properties": {
        "limit": {
          "type": "number",
          "description": "Number of users to return",
          "default": 10
        }
      }
    },
    "action": {
      "type": "select",
      "table": "users",
      "columns": ["id", "name", "email"],
      "limit": "{{limit}}"
    }
  }
]

Supported Action Types

  • select: Query data from tables
  • insert: Create new records
  • update: Modify existing records
  • delete: Remove records

Template Variables

Use Jinja2-style templates in your configurations:

json
{
  "action": {
    "type": "select",
    "table": "{{table_name}}",
    "filters": {
      "id": "{{user_id}}"
    }
  }
}

MCP Client Configuration

Cursor IDE Configuration

Add to your `~/.cursor/mcp.json`:

json
{
  "mcpServers": {
    "supamcpbuilder": {
      "command": "npx",
      "args": [
        "-y",
        "supamcpbuilder",
        "--url", "https://your-project.supabase.co",
        "--anon-key", "your-anon-key",
        "--email", "your-email@example.com",
        "--password", "your-password",
        "--tools-json-base64", "YOUR_BASE64_ENCODED_TOOLS"
      ]
    }
  }
}

Claude Desktop Configuration

Add to your Claude Desktop config:

json
{
  "mcpServers": {
    "supamcpbuilder": {
      "command": "npx",
      "args": [
        "-y",
        "supamcpbuilder",
        "--url", "https://your-project.supabase.co",
        "--anon-key", "your-anon-key",
        "--email", "your-email@example.com",
        "--password", "your-password",
        "--config-path", "/path/to/your/tools-config.json"
      ]
    }
  }
}

Environment Variables

You can also use environment variables:

bash
export SUPABASE_URL="https://your-project.supabase.co"
export SUPABASE_ANON_KEY="your-anon-key"
export SUPABASE_EMAIL="your-email@example.com"
export SUPABASE_PASSWORD="your-password"

supamcpbuilder --config-path "./tools-config.json"

Advanced Configuration

Complex Tool Example

json
[
  {
    "name": "create-user-with-profile",
    "description": "Create a new user with profile information",
    "parameters": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "User's full name"
        },
        "email": {
          "type": "string",
          "description": "User's email address"
        },
        "bio": {
          "type": "string",
          "description": "User's biography"
        }
      },
      "required": ["name", "email"]
    },
    "action": {
      "type": "insert",
      "table": "users",
      "values": {
        "name": "{{name}}",
        "email": "{{email}}",
        "bio": "{{bio}}",
        "created_at": "now()"
      },
      "returning": ["id", "name", "email"]
    }
  }
]

Authentication & Security

  • User Authentication: Uses email/password with automatic JWT refresh
  • Row Level Security: All operations respect your Supabase RLS policies
  • Secure by Default: No admin access, focuses on user-level operations
  • Auto Token Refresh: Handles JWT expiration automatically

Troubleshooting

Common Issues

1. Authentication Errors: Ensure your email/password combination is correct

2. Permission Denied: Check your RLS policies and user permissions

3. Tool Not Found: Verify your JSON configuration syntax

4. Connection Issues: Confirm your Supabase URL and API keys

Debug Mode

Enable debug logging:

bash
DEBUG=supamcpbuilder supamcpbuilder --url ... --anon-key ...

Examples

Check the `examples/` directory for:

  • Sample tool configurations
  • MCP client setup examples
  • Common use cases

Contributing

1. Fork the repository

2. Create your feature branch (`git checkout -b feature/amazing-feature`)

3. Commit your changes (`git commit -m 'Add some amazing feature'`)

4. Push to the branch (`git push origin feature/amazing-feature`)

5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Changelog

v1.0.0

  • Initial release
  • Basic MCP server functionality
  • JSON configuration support
  • Base64 encoding support
  • Authentication handling
  • Template variable support

Frequently asked questions

What is supaMCPBuilder?

supaMCPBuilder is SupaMCP Server

How do I install supaMCPBuilder?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is supaMCPBuilder open source?

Yes — it is hosted on GitHub at https://github.com/vivek100/supaMCPBuilder and has 11 stars.

Related MCP tools

modelcontextprotocolservers

Model Context Protocol Servers

90,051 TypeScript
bytedanceUI-TARS-desktop

The Open-Source Multimodal AI Agent Stack: Connecting Cutting-Edge AI Models and Agent Infra

38,840 TypeScript
agentvlmvision+11
czlonkowskin8n-mcp

A MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you

22,825 TypeScript
mcpmcp-servern8n+1
glipsFigma-Context-MCP

MCP server to provide Figma layout information to AI coding agents like Cursor

15,766 TypeScript
aicursorfigma+2
elie222inbox-zero

The world's best AI personal assistant for email. Open source app to help you reach inbox zero fast.

12,148 TypeScript
aiemailnextjs+14
instantdbinstant

Instant is the best backend for AI-coded apps. You get auth, permissions, storage, presence, and streams — everything you need to ship apps your users will love.

10,507 TypeScript

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP