# mcp-supabasedev

**Repository Path**: larntin/mcp-supabasedev

## Basic Information

- **Project Name**: mcp-supabasedev
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-24
- **Last Updated**: 2026-03-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mcp-supabasedev

Supabase readonly MCP server for AI-assisted development/testing/ops.

## Tech stack

- Node.js 22+
- TypeScript 5+
- `@modelcontextprotocol/sdk`
- `@supabase/supabase-js`
- `zod`, `dotenv`, `pino`

## Install

```bash
npm install
```

## Local config

Priority from high to low:

1. CLI args (`--supabase-url`, `--supabase-key`, `--supabase-access-token`, `--schema`, `--default-limit`, `--max-limit`)
2. Environment variables (`SUPABASE_URL`, `SUPABASE_KEY`, `SUPABASE_SCHEMA`, `SUPABASE_ACCESS_TOKEN`)
3. `config.js`
4. `config.json` (auto fallback when values are missing)

`config.js` example:

```js
export default {
  supabase: {
    url: "https://YOUR_PROJECT.supabase.co",
    apikey: "YOUR_SERVICE_ROLE_KEY",
    accessToken: "sbp_YOUR_PERSONAL_ACCESS_TOKEN", // optional, required for execute_sql
  },
  query: {
    defaultLimit: 50,
    maxLimit: 50,
  },
  schema: "public",
};
```

If you already have `config.json`, you can keep using it directly without changes.

### Personal Access Token（`accessToken`）

`accessToken` 是 Supabase **Personal Access Token**，与项目的 service role key 不同，是账号级别的令牌。

**用途**：仅用于 `execute_sql` 工具。`execute_sql` 底层调用 [Supabase Management API](https://api.supabase.com)，该 API 只接受 Personal Access Token 鉴权，service role key 无法使用。

**获取方式**：登录 Supabase Dashboard → 右上角头像 → **Account** → **Access Tokens** → 生成新 Token。
直达链接：https://supabase.com/dashboard/account/tokens

**安全说明**：Personal Access Token 拥有你账号下所有项目的管理权限，请勿提交到版本控制，建议放在本地 `config.js`（已 git-ignore）或环境变量中。未配置时 `execute_sql` 会正常报错提示，不影响其他工具的使用。

## Scripts

```bash
npm run dev
npm run build
npm run typecheck
npm run lint
npm run test
```

## MCP tools

- `health_check`: checks server and Supabase connectivity.
- `list_tables`: discovers all accessible tables from Supabase OpenAPI.
- `query_table`: readonly data query for all tables.
  - Supports filters (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`, `in`, `is`)
  - Supports sort (`asc` / `desc`)
  - Supports pagination (`offset`, `limit`)
  - Default `limit=50`, max `limit=50`
  - Automatically redacts sensitive fields in the response
- `execute_sql`: executes arbitrary SQL (SELECT / INSERT / UPDATE / DELETE / DDL) via Supabase Management API.
  - Requires `accessToken` (Personal Access Token) — see [Local config](#local-config) for setup
  - No row limit; returns all rows the query produces

## Security notes

- This project is readonly by design (no insert/update/delete tools).
- Keep service role key out of source control.
- Use separate Supabase accounts/projects for dev/test/prod.
- Dev/prod can share the same architecture while switching credentials.

## 开发测试

### 边改边跑源码

```toml
[mcp_servers.supabase_dev_src]
command = "node"
args = [
  "C:/Users/dengd/workspace/sourcecode/mcp-supabasedev/node_modules/tsx/dist/cli.mjs",
  "C:/Users/dengd/workspace/sourcecode/mcp-supabasedev/src/index.ts",
  "--config",
  "C:/Users/dengd/workspace/sourcecode/mcp-supabasedev/config.js",
  "--schema",
  "public",
  "--default-limit",
  "50",
  "--max-limit",
  "50"
]
startup_timeout_sec = 20
tool_timeout_sec = 120
```

注意点：

1. 先在项目里执行一次 npm install（保证 node_modules/tsx/dist/cli.mjs 存在）。
2. 修改源码后，需要重启该 MCP server 进程（通常重启 Codex/重新加载 MCP 配置）。
3. 不要用 npm run dev 作为 MCP command（会带 npm 额外输出，可能干扰 stdio 协议）。

我已经把 dotenv 改为静默模式（quiet: true），避免它再打印启动提示干扰协议。

### 调用 dist

本地开发态建议这样配，关键是不要用 npm run dev 作为 command（会有额外 stdout，可能干扰 MCP stdio 协议）。

```toml
[mcp_servers.supabase_dev]
command = "node"
args = [
  "C:/Users/dengd/workspace/sourcecode/mcp-supabasedev/dist/index.js",
  "--config",
  "C:/Users/dengd/workspace/sourcecode/mcp-supabasedev/config.js",
  "--schema",
  "public",
  "--default-limit",
  "50",
  "--max-limit",
  "50"
]
startup_timeout_sec = 20
tool_timeout_sec = 120
```

本地使用步骤：

1. 在项目目录执行 npm install
2. 执行 npm run build
3. 重启 Codex（让它重新拉起 MCP）
4. 在会话里先调 health_check、再调 list_tables