MCP Server

Install SchemaLens MCP

Give Claude, Cursor, or Windsurf live access to your PostgreSQL schemas. No hosting required — runs locally over stdio, spawned by your client.

Prerequisites

Node.js 18+ on your machine. npx will fetch the server on first use.
A SchemaLens project. Run npx @schemalens/cli init in your repo to create schema/_meta/.schemalens.yml.
A PostgreSQL connection string (Supabase, Neon, RDS, local — anything). The MCP server uses the same env() resolution as the CLI.

1. Add the server to your client

All MCP-compatible clients use the same config shape. Paste this into your client's config file:

{
  "mcpServers": {
    "schemalens": {
      "command": "npx",
      "args": ["-y", "@schemalens/mcp"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@host:5432/dbname"
      }
    }
  }
}

Tip: if your .schemalens.yml already resolves connection strings from env vars or links to the SchemaLens SaaS, omit the env block entirely.

2. Where the config file lives

CLI

Claude Code

.claude/settings.json (project) or ~/.claude/settings.json (user)

macOS / Windows

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

Restart Claude Desktop after editing.

Editor

Cursor

~/.cursor/mcp.json (global) or .cursor/mcp.json (project)

Editor

Windsurf

~/.codeium/windsurf/mcp_config.json

3. Verify it works

Restart your client, then ask your agent something like:

"Introspect the dev database and show me the tables"

"Pull the staging schema to disk"

"Plan a deploy from dev to prod"

The agent should request permission to call schema_introspect, schema_pull, or schema_deploy_plan. Approve and you're live.

Available tools

Tool	Description
schema_introspect	Return a full live-database snapshot (tables, views, functions, triggers, policies, indexes, enums, extensions).
schema_pull	Introspect and write SQL files to schema/<env>/.
schema_status	Diff local files against live DB.
schema_diff	Compare two live environments.
schema_list_objects	List objects in local schema files.
schema_get_object	Read one object's SQL from disk.
schema_deploy_plan	Dependency-ordered deploy plan — dry run only.
schema_deploy_apply	Execute a deploy plan. Destructive operations require allowDestructive: true.

Safety

Destructive ops are opt-in. schema_deploy_apply refuses DROP / ALTER TYPE unless called with allowDestructive: true.
Transactional. Apply runs inside a single transaction — failures roll back the batch.
Credentials stay local. Connection strings never leave your machine and are never echoed in tool responses or logs.
Supabase-managed schemas are filtered. auth, storage, realtime, etc. are excluded from diffs and deploys.

Troubleshooting

Server doesn't start / tools don't appear

Restart your client after editing the config. Check the client's MCP log for stderr from the server — startup errors (missing .schemalens.yml, unresolved env vars, unreachable DB) print there.

"Config not found" error

The server looks for schema/_meta/.schemalens.yml in the working directory where your client launches it. Open your project directory in the client first, or add "cwd": "/abs/path/to/repo" to the server entry.

"Environment variable DATABASE_URL is not set"

Either set the value in the env block of your MCP config, or use a .env file in your project root — the server loads it on startup.

Want to pin a specific version?

Replace @schemalens/mcp with @schemalens/mcp@0.1.0 in the args array.

Prefer a shell-driven workflow? Read the CLI guide →