Berth MCP Server

Berth -- Database MCP Server

A secure berth for your data -- database access for AI tools.

Berth is a Model Context Protocol server that gives AI assistants safe, structured access to PostgreSQL, SQLite, and MySQL databases. It exposes 13 tools for inspecting schemas, running queries, managing data, generating migrations, and performing backups -- all governed by a 3-tier safety model that prevents accidental damage.

---

Safety Model

Berth enforces three operating modes that control what SQL is permitted:

The server starts in read-only mode. Write and admin modes must be explicitly enabled. Destructive operations in admin mode generate a one-time confirmation token that expires after 60 seconds -- the AI must echo the token back to confirm intent.

---

Tools

---

Schema Migrations

The generate_migration tool compares two schemas and produces dialect-aware SQL to migrate from one to the other. Two modes of operation:

Mode 1 — Live database vs. target DDL:

Provide connection_id (an active connection) and target_sql (CREATE TABLE statements describing the desired schema). Berth introspects the live database and diffs it against the parsed target.

Mode 2 — Two live databases:

Provide from_connection and to_connection (two active connection IDs). Berth introspects both and generates the migration to transform the source into the target.

What it generates:

• CREATE TABLE for new tables
• ALTER TABLE ADD COLUMN for new columns
• ALTER TABLE ALTER COLUMN / MODIFY COLUMN for type, nullability, and default changes
• CREATE INDEX / DROP INDEX for index changes
• ADD CONSTRAINT / DROP CONSTRAINT for foreign key changes
• DROP TABLE and DROP COLUMN are commented out with warnings (safety first)

Dialect handling:

• PostgreSQL -- uses ALTER COLUMN ... TYPE, SET/DROP NOT NULL, SET/DROP DEFAULT
• MySQL -- uses MODIFY COLUMN for all column changes, DROP INDEX ... ON table
• SQLite -- warns about unsupported operations and includes the table rebuild pattern for changes that require it (ALTER COLUMN, DROP COLUMN on older versions, constraint changes)

---

Supported Databases

• PostgreSQL -- full support including pg_stat_activity, EXPLAIN ANALYZE, pg_dump/psql backup/restore
• SQLite -- full support including PRAGMA introspection, .backup/.restore via sqlite3 CLI
• MySQL -- full support including information_schema introspection, mysqldump/mysql backup/restore

---

Installation

From PyPI:

pip install berth-mcp

Or in an isolated environment:

pipx install berth-mcp

MySQL support requires an optional dependency:

pip install berth-mcp[mysql]

PostgreSQL (asyncpg) and SQLite (aiosqlite) drivers are included by default.

---

Usage

Run the server:

berth

Berth communicates over stdio using the MCP protocol. It is designed to be launched by an MCP client, not run standalone.

Claude Code

claude mcp add berth -- berth

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "berth": {
      "command": "berth",
      "args": []
    }
  }
}

If installed in a virtual environment, use the full path:

{
  "mcpServers": {
    "berth": {
      "command": "/path/to/venv/bin/berth",
      "args": []
    }
  }
}

---

Environment Variables

---

Security

• 3-tier safety model -- read-only by default, writes require explicit opt-in, destructive ops require confirmation tokens
• Confirmation tokens -- one-time UUIDs with 60-second expiry for DROP, TRUNCATE, ALTER DROP, and full-table DELETE
• SQL injection protection -- table names validated against sqlite_master before use in PRAGMA statements; parameterized queries used throughout
• Path traversal protection -- backup/restore paths are resolved and validated to stay within BERTH_BACKUP_DIR; null bytes rejected
• Password masking -- DSN passwords are masked in all display output and error messages

---

Development

git clone https://github.com/seayniclabs/berth.git
cd berth
python -m venv .venv && source .venv/bin/activate
pip install -e ".[test]"
python -m pytest tests/ -q

Integration tests for PostgreSQL and MySQL require Docker:

docker compose -f tests/docker-compose.test.yml up -d
python -m pytest tests/ -q
docker compose -f tests/docker-compose.test.yml down

---

License

MIT