npm package: @iflow-mcp/dynamicendpoints-supabase-mcp
Description: [![smithery badge](https://smithery.ai/badge/supabase-server)](https://smithery.ai/server/supabase-server) A Model Context Protocol (MCP) server that provides comprehensive tools for interacting with Supabase databases, storage, and edge functions. This s
Latest version: 0.1.0

# Supabase MCP Server

[![smithery badge](https://smithery.ai/badge/supabase-server)](https://smithery.ai/server/supabase-server)
A Model Context Protocol (MCP) server that provides comprehensive tools for interacting with Supabase databases, storage, and edge functions. This server enables seamless integration between Supabase services and MCP-compatible applications.

<a href="https://glama.ai/mcp/servers/vwi6nt8i80"><img width="380" height="200" src="https://glama.ai/mcp/servers/vwi6nt8i80/badge" alt="supabase-mcp MCP server" /></a>

## Overview

The Supabase MCP server acts as a bridge between MCP clients and Supabase's suite of services, providing:

- Database operations with rich querying capabilities
- Storage management for files and assets
- Edge function invocation
- Project and organization management
- User authentication and management
- Role-based access control

## Architecture

The server is built using TypeScript and follows a modular architecture:

```
supabase-server/
├── src/
│   ├── index.ts              # Main server implementation
│   └── types/
│       └── supabase.d.ts     # Type definitions
├── package.json
├── tsconfig.json
├── config.json.example       # Example configuration file
└── .env.example             # Environment variables template
```

### Key Components

- **Server Class**: Implements the MCP server interface and handles all client requests
- **Type Definitions**: Comprehensive TypeScript definitions for all operations
- **Environment Configuration**: Secure configuration management via environment variables
- **Error Handling**: Robust error handling with detailed error messages

## Prerequisites

- Node.js 16.x or higher
- A Supabase project with:
  - Project URL
  - Service Role Key (for admin operations)
  - Access Token (for management operations)
- MCP-compatible client

## Installation

### Installing via Smithery

To install Supabase Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/supabase-server):

```bash
npx -y @smithery/cli install supabase-server --client claude
```

1. Clone the repository:
```bash
git clone https://github.com/DynamicEndpoints/supabase-mcp.git
cd supabase-mcp
```

2. Install dependencies:
```bash
npm install
```

3. Create environment configuration:
```bash
cp .env.example .env
```

4. Configure environment variables:
```bash
SUPABASE_URL=your_project_url_here
SUPABASE_KEY=your_service_role_key_here
SUPABASE_ACCESS_TOKEN=your_access_token_here  # Required for management operations
```

5. Create server configuration:
```bash
cp config.json.example config.json
```

6. Build the server:
```bash
npm run build
```

## Configuration

The server supports extensive configuration through both environment variables and a config.json file. Here's a detailed breakdown of the configuration options:

### Server Configuration
```json
{
  "server": {
    "name": "supabase-server",    // Server name
    "version": "0.1.0",           // Server version
    "port": 3000,                 // Port number (if running standalone)
    "host": "localhost"           // Host address (if running standalone)
  }
}
```

### Supabase Configuration
```json
{
  "supabase": {
    "project": {
      "url": "your_project_url",
      "key": "your_service_role_key",
      "accessToken": "your_access_token"
    },
    "storage": {
      "defaultBucket": "public",           // Default storage bucket
      "maxFileSize": 52428800,            // Max file size in bytes (50MB)
      "allowedMimeTypes": [               // Allowed file types
        "image/*",
        "application/pdf",
        "text/*"
      ]
    },
    "database": {
      "maxConnections": 10,               // Max DB connections
      "timeout": 30000,                   // Query timeout in ms
      "ssl": true                         // SSL connection
    },
    "auth": {
      "autoConfirmUsers": false,          // Auto-confirm new users
      "disableSignup": false,             // Disable public signups
      "jwt": {
        "expiresIn": "1h",               // Token expiration
        "algorithm": "HS256"              // JWT algorithm
      }
    }
  }
}
```

### Logging Configuration
```json
{
  "logging": {
    "level": "info",                      // Log level
    "format": "json",                     // Log format
    "outputs": ["console", "file"],       // Output destinations
    "file": {
      "path": "logs/server.log",          // Log file path
      "maxSize": "10m",                   // Max file size
      "maxFiles": 5                       // Max number of files
    }
  }
}
```

### Security Configuration
```json
{
  "security": {
    "cors": {
      "enabled": true,
      "origins": ["*"],
      "methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
      "allowedHeaders": ["Content-Type", "Authorization"]
    },
    "rateLimit": {
      "enabled": true,
      "windowMs": 900000,                 // 15 minutes
      "max": 100                          // Max requests per window
    }
  }
}
```

### Monitoring Configuration
```json
{
  "monitoring": {
    "enabled": true,
    "metrics": {
      "collect": true,
      "interval": 60000                   // Collection interval in ms
    },
    "health": {
      "enabled": true,
      "path": "/health"                   // Health check endpoint
    }
  }
}
```

See `config.json.example` for a complete example configuration file.

## MCP Integration

Add the server to your MCP settings (cline_mcp_settings.json):

```json
{
  "mcpServers": {
    "supabase": {
      "command": "node",
      "args": ["path/to/supabase-server/build/index.js"],
      "env": {
        "SUPABASE_URL": "your_project_url",
        "SUPABASE_KEY": "your_service_role_key",
        "SUPABASE_ACCESS_TOKEN": "your_access_token"
      },
      "config": "path/to/config.json"  // Optional: path to configuration file
    }
  }
}
```

## Available Tools

### Database Operations

#### create_record
Create a new record in a table with support for returning specific fields.

```typescript
{
  table: string;
  data: Record<string, any>;
  returning?: string[];
}
```

Example:
```typescript
{
  table: "users",
  data: {
    name: "John Doe",
    email: "john@example.com"
  },
  returning: ["id", "created_at"]
}
```

#### read_records
Read records with advanced filtering, joins, and field selection.

```typescript
{
  table: string;
  select?: string[];
  filter?: Record<string, any>;
  joins?: Array<{
    type?: 'inner' | 'left' | 'right' | 'full';
    table: string;
    on: string;
  }>;
}
```

Example:
```typescript
{
  table: "posts",
  select: ["id", "title", "user.name"],
  filter: { published: true },
  joins: [{
    type: "left",
    table: "users",
    on: "posts.user_id=users.id"
  }]
}
```

#### update_record
Update records with filtering and returning capabilities.

```typescript
{
  table: string;
  data: Record<string, any>;
  filter?: Record<string, any>;
  returning?: string[];
}
```

Example:
```typescript
{
  table: "users",
  data: { status: "active" },
  filter: { email: "john@example.com" },
  returning: ["id", "status", "updated_at"]
}
```

#### delete_record
Delete records with filtering and returning capabilities.

```typescript
{
  table: string;
  filter?: Record<string, any>;
  returning?: string[];
}
```

Example:
```typescript
{
  table: "posts",
  filter: { status: "draft" },
  returning: ["id", "title"]
}
```

### Storage Operations

#### upload_file
Upload files to Supabase Storage with configurable options.

```typescript
{
  bucket: string;
  path: string;
  file: File | Blob;
  options?: {
    cacheControl?: string;
    contentType?: string;
    upsert?: boolean;
  };
}
```

Example:
```typescript
{
  bucket: "avatars",
  path: "users/123/profile.jpg",
  file: imageBlob,
  options: {
    contentType: "image/jpeg",
    upsert: true
  }
}
```

#### download_file
Download files from Supabase Storage.

```typescript
{
  bucket: string;
  path: string;
}
```

Example:
```typescript
{
  bucket: "documents",
  path: "reports/annual-2023.pdf"
}
```

### Edge Functions

#### invoke_function
Invoke Supabase Edge Functions with parameters and custom options.

```typescript
{
  function: string;
  params?: Record<string, any>;
  options?: {
    headers?: Record<string, string>;
    responseType?: 'json' | 'text' | 'arraybuffer';
  };
}
```

Example:
```typescript
{
  function: "process-image",
  params: {
    url: "https://example.com/image.jpg",
    width: 800
  },
  options: {
    responseType: "json"
  }
}
```

### User Management

#### list_users
List users with pagination support.

```typescript
{
  page?: number;
  per_page?: number;
}
```

#### create_user
Create a new user with metadata.

```typescript
{
  email: string;
  password: string;
  data?: Record<string, any>;
}
```

#### update_user
Update user details.

```typescript
{
  user_id: string;
  email?: string;
  password?: string;
  data?: Record<string, any>;
}
```

#### delete_user
Delete a user.

```typescript
{
  user_id: string;
}
```

#### assign_user_role
Assign a role to a user.

```typescript
{
  user_id: string;
  role: string;
}
```

#### remove_user_role
Remove a role from a user.

```typescript
{
  user_id: string;
  role: string;
}
```

## Error Handling

The server provides detailed error messages for common scenarios:

- Invalid parameters
- Authentication failures
- Permission issues
- Rate limiting
- Network errors
- Database constraints

Errors are returned in a standardized format:

```typescript
{
  code: ErrorCode;
  message: string;
  details?: any;
}
```

## Development

### Running Tests
```bash
npm test
```

### Building
```bash
npm run build
```

### Linting
```bash
npm run lint
```

### Running evals 

The evals package loads an mcp client that then runs the index.ts file, so there is no need to rebuild between tests. You can load environment variables by prefixing the npx command. Full documentation can be found [here](https://www.mcpevals.io/docs).

```bash
OPENAI_API_KEY=your-key  npx mcp-eval src/evals/evals.ts src/index.ts
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## License

MIT License - see LICENSE for details

## Support

For support, please:

1. Check the [issues](https://github.com/DynamicEndpoints/supabase-mcp/issues) for existing problems/solutions
2. Create a new issue with detailed reproduction steps
3. Include relevant error messages and environment details