sequel-mcp

library0.8.0jsnpmunverified

A Model Context Protocol server for MySQL/MariaDB and SQLite that lets AI agents run SQL queries with policy-gated action sets (allow/confirm/deny per category), pre-mutation backups, immutable audit log, macOS Keychain credential storage for MySQL/MariaDB, and optional Sequel Ace import. Current version is 0.8.0, with active development and monthly releases. Key differentiators: two-layer permissions (connection-level + per-database overrides), session-scoped confirm grants, built-in backup/restore, SSH tunnel support, and Docker exec bridge. Fully standalone; Sequel Ace integration is optional bootstrap convenience. Ships TypeScript types, requires Node >=20.0.0. Primarily designed for Claude Code, Codex CLI, or any MCP client.

database

npm install sequel-mcp

package ↗

INSTALL

IMPORT

SIG · SEQUEL-MCP

sequel-mcp

databasejavascriptv0.8.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default export (server)

✓ import sequelMcp from 'sequel-mcp'

✗ const sequelMcp = require('sequel-mcp')

Package is ESM-only; no CommonJS support. Use import syntax.

createServer

✓ import { createServer } from 'sequel-mcp'

Main function to start the MCP server programmatically.

types (TS)

✓ import type { ConnectionConfig, PolicyConfig } from 'sequel-mcp'

TypeScript types are shipped with the package.

Starts a sequel-mcp server with a SQLite connection, policy-gated permissions, and audit logging.

import { createServer } from 'sequel-mcp'; import { config } from 'dotenv'; config(); const server = await createServer({ port: Number(process.env.MCP_PORT ?? '3000'), connections: [ { name: 'my-sqlite', driver: 'sqlite', database: process.env.SQLITE_PATH ?? './data.db', }, ], policies: { 'my-sqlite': { read: 'allow', write: 'confirm', ddl: 'deny', admin: 'deny', txCtrl: 'confirm', }, }, audit: { enabled: true, prevHash: true, }, }); await server.start(); console.log('sequel-mcp server running on port', process.env.MCP_PORT ?? '3000');

Debug

Known issues

breakingIn v0.5.0, the `hostKeyPolicy` default changed from 'lenient' to 'strict' for SSH connections. Existing setups may fail if known_hosts is missing.

fix

Either add host keys to ~/.ssh/known_hosts or explicitly set hostKeyPolicy: 'lenient' in connection config.

affects: >=0.5.0

breakingIn v0.6.0, `confirm` prompts changed to a four-choice radio (Allow once / Allow for session / Allow always / Decline). Scripts expecting simple yes/no confirmation will break.

fix

Update your MCP client to handle the new structured prompt format (4 options).

affects: >=0.6.0

breakingIn v0.7.0, tool results changed to structuredContent format. Clients that parse raw JSON output may break.

fix

Use structuredContent format: each result is an array of objects with {type, text} fields.

affects: >=0.7.0

deprecatedThe `add_sequel_ace_connection` tool is deprecated in favor of `import_from_sequel_ace`. It will be removed in v1.0.

fix

Use `import_from_sequel_ace` instead.

affects: >=0.8.0

gotchaSQLite connections require Node >=20 and the built-in sqlite module. No password support.

fix

Ensure you're using Node 20+; use add_sqlite_connection tool without password.

affects: >=0.8.0

gotchamacOS Keychain storage is non-syncable and device-only. Moving to a new Mac will require re-entering credentials.

fix

Export credentials before migration using the export tool (if available) or re-add manually.

affects: >=0.5.0

gotchaWhen using SSH tunnel with TLS, set sslServerName explicitly to the original database hostname; otherwise certificate verification may fail.

fix

Add sslServerName: 'actual-db-hostname.com' to the connection config.

affects: >=0.5.0

Errors

Common errors & fixes

Error: SQLITE_ERROR: no such table: main.foo

Trying to query a table in a SQLite database that doesn't exist or wrong database path.

fix

Check that the SQLite database file exists at the specified path and the table name is correct.

Error: Policy denied: write operation on database 'production'

A write operation (INSERT/UPDATE/DELETE) was attempted on a database with a policy that denies writes.

fix

Update the policy for that connection to 'allow' or 'confirm' for the write category, or switch to a read-only query.

Error: ENOENT: no such file or directory, open '/Users/user/.ssh/known_hosts'

SSH hostKeyPolicy is set to 'strict' but ~/.ssh/known_hosts does not exist.

fix

Either set hostKeyPolicy: 'lenient' in connection config, or add the remote host's key to ~/.ssh/known_hosts.

Error: Connection refused: connect ECONNREFUSED 127.0.0.1:3306

SSH tunnel was established but the local port forwarding target (MySQL) is not running on the remote end.

fix

Ensure MySQL/MariaDB is running on the remote server and listening on the expected port (default 3306).

error:0308010C:digital envelope routines::unsupported

OpenSSL version mismatch on Node 17+ when using older crypto algorithms.

fix

Set NODE_OPTIONS=--openssl-legacy-provider or upgrade to a compatible MySQL client library.

Upgrade

Version history

0.8.0latest on npm

Audit

Dependencies

ssh2optionalSSH tunnel support for remote MySQL/MariaDB connections

Agent activity

13 hits · last 30 days

node