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 "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