# 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](LICENSE) file for details.
## Support
- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/vivek100/supaMCPBuilder/issues)
- 💡 **Feature Requests**: [GitHub Discussions](https://github.com/vivek100/supaMCPBuilder/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
