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)

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

Installation

npm install -g supamcpbuilder

Configuration Options

Basic Usage

supamcpbuilder \
  --url "https://your-project.supabase.co" \
  --anon-key "your-anon-key" \
  --email "[email protected]" \
  --password "your-password"

With JSON Configuration File

supamcpbuilder \
  --url "https://your-project.supabase.co" \
  --anon-key "your-anon-key" \
  --email "[email protected]" \
  --password "your-password" \
  --config-path "./tools-config.json"

With Base64 Encoded Tools

supamcpbuilder \
  --url "https://your-project.supabase.co" \
  --anon-key "your-anon-key" \
  --email "[email protected]" \
  --password "your-password" \
  --tools-json-base64 "W3sibmFtZSI6Imxpc3QtdXNlcnMiLCJkZXNjcmlwdGlvbiI6Ikxpc3QgYWxsIHVzZXJzIn1d"

Tool Configuration Format

Basic Tool Structure

[
  {
    "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:

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

MCP Client Configuration

Cursor IDE Configuration

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

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

Claude Desktop Configuration

Add to your Claude Desktop config:

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

Environment Variables

You can also use environment variables:

export SUPABASE_URL="https://your-project.supabase.co"
export SUPABASE_ANON_KEY="your-anon-key"
export SUPABASE_EMAIL="[email protected]"
export SUPABASE_PASSWORD="your-password"

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

Advanced Configuration

Complex Tool Example

[
  {
    "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:

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

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📖 Documentation: Check the examples directory for more details

Changelog

v1.0.0

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