Skip to content
Back to search

mcp-server-test

Test repository created via GitHub MCP server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/d-manoharan--mcp-server-test/badge.svg)](/listings/d-manoharan--mcp-server-test)

HTML

<a href="/listings/d-manoharan--mcp-server-test"><img src="/api/listings/d-manoharan--mcp-server-test/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/d-manoharan/mcp-server-test.git
cd mcp-server-test
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e .
cp .env.example .env
# edit .env and replace the DATABASE_URL placeholder
pytest -q                          # optional: smoke tests need no database

Then point your MCP client at `.venv/bin/supabase-postgres-mcp` (see below), or run it manually:

python -m supabase_postgres_mcp

> The server speaks MCP over **stdio**, so it will appear to hang when run in a > terminal. That is expected — normally your MCP client launches it.

Using uv (optional)

uv sync
uv run supabase-postgres-mcp

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 291 lines
  1. # supabase-postgres-mcp
  2. A [FastMCP](https://gofastmcp.com) server that lets MCP clients (Claude Desktop,
  3. VS Code, Cursor, OpenCode, ...) inspect and query a **Supabase Postgres**
  4. database.
  5. - **One setting to configure:** a Postgres connection string (`DATABASE_URL`).
  6. - **Read-only by default.** `SELECT`, `WITH`, `SHOW`, and `EXPLAIN` run inside a
  7. read-only transaction. Writes require an explicit opt-in at startup.
  8. - **Supabase-aware.** `sslmode=require` (what the Supabase dashboard emits) is
  9. handled by libpq, TLS is enabled automatically for Supabase hosts, and
  10. prepared statements are disabled for Supavisor/PgBouncer compatibility.
  11. - **`$1` placeholders.** The tool API accepts Supabase-style `$1, $2, ...`
  12. parameters (translated safely for psycopg); `%s`-style SQL also works.
  13. - **Starts without a connection string** so clients can always connect; tool
  14. calls then return an actionable error instead of crashing the process.
  15. - **Guarded execution.** One statement per call, transaction-control and `COPY`
  16. statements rejected, statement timeout, and a row cap.
  17. ## Tools
  18. | Tool | Writes | Description |
  19. | --- | --- | --- |
  20. | `list_schemas` | no | List non-system schemas (usually `public`). |
  21. | `list_tables` | no | List tables/views in a schema with their comments. |
  22. | `describe_table` | no | Columns, types, primary key, foreign keys, indexes, comment. |
  23. | `query` | no | Run one read-only SQL statement with `$1`-style parameters. |
  24. | `execute` | **yes** | Run one `INSERT`/`UPDATE`/`DELETE`/DDL statement. Only registered when `ALLOW_WRITES=true`. |
  25. `query` results look like:
  26. ```json
  27. {
  28. "status": "SELECT 42",
  29. "row_count": 42,
  30. "returned_rows": 42,
  31. "truncated": false,
  32. "max_rows": 100,
  33. "duration_ms": 12,
  34. "fields": [{ "name": "id", "type_code": 23 }],
  35. "rows": [{ "id": 1 }]
  36. }
  37. ```
  38. `row_count` is what Postgres reports; `returned_rows` is what was sent back.
  39. `truncated` is `true` when more rows existed than `max_rows` allowed. Add a
  40. `LIMIT` to your SQL when you expect large result sets.
  41. Values are JSON-normalized for MCP: `numeric`/`int8` become strings, dates and
  42. timestamps become ISO-8601 strings, `bytea` becomes base64, and duplicate column
  43. names are suffixed (`id`, `id_2`).
  44. ## Quick start
  45. ```bash
  46. git clone https://github.com/d-manoharan/mcp-server-test.git
  47. cd mcp-server-test
  48. python3 -m venv .venv
  49. source .venv/bin/activate # Windows: .venv\Scripts\activate
  50. pip install -e .
  51. cp .env.example .env
  52. # edit .env and replace the DATABASE_URL placeholder
  53. pytest -q # optional: smoke tests need no database
  54. ```
  55. Then point your MCP client at `.venv/bin/supabase-postgres-mcp` (see below), or
  56. run it manually:
  57. ```bash
  58. python -m supabase_postgres_mcp
  59. ```
  60. > The server speaks MCP over **stdio**, so it will appear to hang when run in a
  61. > terminal. That is expected — normally your MCP client launches it.
  62. ### Using uv (optional)
  63. ```bash
  64. uv sync
  65. uv run supabase-postgres-mcp
  66. ```
  67. ## The connection string
  68. Copy it from **Supabase Dashboard → Project Settings → Database → Connection
  69. string**. Replace only the placeholders:
  70. ```dotenv
  71. DATABASE_URL=postgresql://postgres.<PROJECT_REF>:<YOUR_DB_PASSWORD>@aws-0-<REGION>.pooler.supabase.com:6543/postgres?sslmode=require
  72. ```
  73. Three forms are supported:
  74. | Mode | Port | Host | Notes |
  75. | --- | --- | --- | --- |
  76. | Transaction pooler | `6543` | `aws-0-<REGION>.pooler.supabase.com` | **Recommended.** IPv4-compatible, good for short-lived MCP processes. No session-level features (`LISTEN`, advisory locks across calls, ...). |
  77. | Session pooler | `5432` | `aws-0-<REGION>.pooler.supabase.com` | IPv4-compatible with session-level features. |
  78. | Direct | `5432` | `db.<PROJECT_REF>.supabase.co` | IPv6-only by default; use only if your network supports IPv6. |
  79. Tips:
  80. - The pooler username is `postgres.<PROJECT_REF>`, **not** just `postgres`.
  81. - URL-encode special characters in the password: `p@ss` → `p%40ss`, `#` → `%23`.
  82. - Keep `?sslmode=require` (or `verify-full` if you want certificate
  83. verification). If you omit it on a Supabase host, TLS is enabled automatically.
  84. - Prisma-style parameters such as `?pgbouncer=true&connection_limit=1` are
  85. dropped automatically because libpq does not understand them.
  86. The server loads `.env` from the current directory or from next to
  87. `pyproject.toml`. Real environment variables always win, so client config takes
  88. precedence over the file.
  89. ## MCP client configuration
  90. Replace `/absolute/path/to/mcp-server-test` with the real path.
  91. ### Claude Desktop
  92. `claude_desktop_config.json`:
  93. ```json
  94. {
  95. "mcpServers": {
  96. "supabase-postgres": {
  97. "command": "/absolute/path/to/mcp-server-test/.venv/bin/supabase-postgres-mcp",
  98. "env": {
  99. "DATABASE_URL": "postgresql://postgres.<PROJECT_REF>:<PASSWORD>@aws-0-<REGION>.pooler.supabase.com:6543/postgres?sslmode=require"
  100. }
  101. }
  102. }
  103. }
  104. ```
  105. ### VS Code
  106. `.vscode/mcp.json`:
  107. ```json
  108. {
  109. "servers": {
  110. "supabase-postgres": {
  111. "type": "stdio",
  112. "command": "/absolute/path/to/mcp-server-test/.venv/bin/supabase-postgres-mcp",
  113. "env": {
  114. "DATABASE_URL": "postgresql://postgres.<PROJECT_REF>:<PASSWORD>@aws-0-<REGION>.pooler.supabase.com:6543/postgres?sslmode=require"
  115. }
  116. }
  117. }
  118. }
  119. ```
  120. ### OpenCode
  121. `opencode.json`:
  122. ```json
  123. {
  124. "$schema": "https://opencode.ai/config.json",
  125. "mcp": {
  126. "supabase-postgres": {
  127. "type": "local",
  128. "command": ["/absolute/path/to/mcp-server-test/.venv/bin/supabase-postgres-mcp"],
  129. "enabled": true,
  130. "environment": {
  131. "DATABASE_URL": "postgresql://postgres.<PROJECT_REF>:<PASSWORD>@aws-0-<REGION>.pooler.supabase.com:6543/postgres?sslmode=require"
  132. }
  133. }
  134. }
  135. }
  136. ```
  137. ### Cursor
  138. `.cursor/mcp.json`:
  139. ```json
  140. {
  141. "mcpServers": {
  142. "supabase-postgres": {
  143. "command": "/absolute/path/to/mcp-server-test/.venv/bin/supabase-postgres-mcp",
  144. "env": {
  145. "DATABASE_URL": "postgresql://postgres.<PROJECT_REF>:<PASSWORD>@aws-0-<REGION>.pooler.supabase.com:6543/postgres?sslmode=require"
  146. }
  147. }
  148. }
  149. }
  150. ```
  151. If you prefer not to put the URL in client config, copy `.env.example` to
  152. `.env` next to `pyproject.toml` and omit the `env` block.
  153. ## Configuration
  154. | Variable | Default | Description |
  155. | --- | --- | --- |
  156. | `DATABASE_URL` | — | Supabase Postgres connection string. Also accepts `SUPABASE_DB_URL`, `POSTGRES_URL`, or `PG_CONNECTION_STRING`. |
  157. | `ALLOW_WRITES` | `false` | Set to `true` to register the `execute` tool. Restart required. |
  158. | `MAX_ROWS` | `100` | Default row cap for `query` (1–1000). |
  159. | `STATEMENT_TIMEOUT_MS` | `15000` | Server-side statement timeout (1000–120000). |
  160. | `POOL_MAX` | `5` | Maximum pooled connections (1–20). |
  161. | `CONNECT_TIMEOUT_S` | `10` | TCP connect timeout (1–60). |
  162. | `APPLICATION_NAME` | `supabase-postgres-mcp` | Shown in `pg_stat_activity`. |
  163. | `MCP_NO_DOTENV` | unset | Set to `1`/`true` to ignore `.env` files. |
  164. | `DOTENV_CONFIG_PATH` | unset | Explicit `.env` file to load. |
  165. ## Safety
  166. - Every `query` runs in `BEGIN` + `SET TRANSACTION READ ONLY` and is rolled
  167. back (`force_rollback=True`). Postgres rejects writes with
  168. `25006 read_only_sql_transaction`.
  169. - Only one statement per call is allowed. Strings, quoted identifiers,
  170. dollar-quoted bodies, and comments are understood by the splitter, so a
  171. payload such as `COMMIT; DELETE ...` is rejected. `BEGIN`/`COMMIT`/
  172. `ROLLBACK`/`SAVEPOINT` and `COPY` are blocked explicitly.
  173. - `execute` is not registered unless `ALLOW_WRITES=true`, and it **commits
  174. immediately**. There is no preview or undo.
  175. - The server connects with the role in `DATABASE_URL`. Connecting as
  176. `postgres` **bypasses Row Level Security**. For read-only usage, prefer a
  177. dedicated role:
  178. ```sql
  179. create role mcp_reader login password '<strong-password>';
  180. grant usage on schema public to mcp_reader;
  181. grant select on all tables in schema public to mcp_reader;
  182. alter default privileges in schema public grant select on tables to mcp_reader;
  183. ```
  184. Then use `postgresql://mcp_reader.<PROJECT_REF>:<password>@...` (pooler) or
  185. `postgresql://mcp_reader:<password>@db.<PROJECT_REF>.supabase.co:5432/postgres`.
  186. - Passwords placed in `.env` or client config are stored in plain text. Keep
  187. `.env` out of version control (it is git-ignored) and rotate credentials if
  188. they leak.
  189. ## Troubleshooting
  190. | Symptom | Likely fix |
  191. | --- | --- |
  192. | `DATABASE_URL is not set` | Set it in the client config, the shell, or `.env` next to `pyproject.toml`. |
  193. | `getaddrinfo ENOTFOUND` / connection timeout | Use the pooler host (`...pooler.supabase.com`, port 6543) — direct hosts are often IPv6-only. |
  194. | `Tenant or user not found` | Username must be `postgres.<PROJECT_REF>` for the pooler, and the region must match the project. |
  195. | `password authentication failed` | Re-copy the password; URL-encode special characters. |
  196. | `server does not support SSL` | Remove `sslmode` for a local Postgres; Supabase requires TLS. |
  197. | `invalid connection option "..."` | Remove unsupported URL parameters, or open an issue; common Prisma parameters are already stripped. |
  198. | `cannot execute INSERT in a read-only transaction` | Use `execute` (requires `ALLOW_WRITES=true`) or run the write in the Supabase SQL editor. |
  199. | `prepared statement "..." does not exist` | The server already disables prepared statements for the pooler. If you use another client, set `prepare_threshold=None` / `statement_cache_size=0`. |
  200. | `Only one SQL statement is allowed` | Send one statement per tool call. |
  201. ## Development
  202. ```bash
  203. python3 -m venv .venv
  204. source .venv/bin/activate
  205. pip install -e '.[dev]'
  206. pytest -q
  207. TEST_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/postgres \
  208. python scripts/integration.py
  209. ```
  210. The integration test creates a `mcp_it_*` schema, exercises every tool, and
  211. drops the schema. Run it against a disposable database, never production.
  212. ### Layout
  213. ```
  214. src/supabase_postgres_mcp/
  215. config.py environment parsing and .env loading
  216. db.py pool, TLS defaults, read-only/write execution
  217. sql.py single-statement validation and $n parameter binding
  218. server.py FastMCP server and tool definitions
  219. tests/ unit and smoke tests (no database required)
  220. scripts/ integration test against a real database
  221. ```
  222. ## Limitations
  223. - stdio transport only (no HTTP).
  224. - No migration, schema-editing, or Supabase Management API features; this is a
  225. focused SQL access server.
  226. - libpq buffers each result, so the row cap limits what is returned but not
  227. what the server sends over the wire. Use `LIMIT` for very large tables; the
  228. statement timeout is the backstop.
  229. - Transaction pooler connections cannot keep session state between calls.
  230. - `COPY` is not supported.
  231. - `ALLOW_WRITES` is read at startup; restart the server after changing it.
  232. ## License
  233. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.