Provides runtime-configurable tools for interacting with Supabase databases, supporting select, insert, update, and delete operations with authentication, automatic JWT token refresh, and template-based dynamic tool generation through JSON configuration.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@SupaMCPBuilderlist the last 5 users from the users table"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_TOOLSInstallation
npm install -g supamcpbuilderConfiguration Options
Basic Usage
supamcpbuilder \
--url "https://your-project.supabase.co" \
--anon-key "your-anon-key" \
--email "your-email@example.com" \
--password "your-password"With JSON Configuration File
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
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
[
{
"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", "your-email@example.com",
"--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", "your-email@example.com",
"--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="your-email@example.com"
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
Authentication Errors: Ensure your email/password combination is correct
Permission Denied: Check your RLS policies and user permissions
Tool Not Found: Verify your JSON configuration syntax
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
Fork the repository
Create your feature branch (
git checkout -b feature/amazing-feature)Commit your changes (
git commit -m 'Add some amazing feature')Push to the branch (
git push origin feature/amazing-feature)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
This server cannot be installed
Resources
Looking for Admin?
Admins can modify the Dockerfile, update the server description, and track usage metrics. If you are the server author, to access the admin panel.