{
  "markdown": "# SafeDB MCP\n\n[![CI](https://github.com/narekmalk/safedb-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/narekmalk/safedb-mcp/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/%40safedb%2Fsafedb-mcp)](https://www.npmjs.com/package/@safedb/safedb-mcp)\n[![safedb-mcp MCP server](https://glama.ai/mcp/servers/narekmalk/safedb-mcp/badges/score.svg)](https://glama.ai/mcp/servers/narekmalk/safedb-mcp)\n\nSafeDB MCP is a secure Model Context Protocol server that lets AI agents inspect and query Postgres, MySQL, MariaDB, and SQLite with strict read-only guardrails. It is designed for teams that want useful database access without handing an agent unrestricted production credentials.\n\nDirect database credentials are dangerous for agents because a single bad prompt, tool call, or generated SQL statement can mutate data, exfiltrate sensitive columns, or run expensive queries. SafeDB MCP puts a policy layer between the agent and your database: only configured schemas and tables are visible, SQL is parsed and validated before execution, row counts are capped, results are masked, and every query attempt is audited.\n\nThis project is an MVP. It prefers false positives and blocked queries over unsafe access, and it does not claim perfect SQL security.\n\n## Features\n\n- MCP tools: `list_schemas`, `list_tables`, `describe_table`, `run_readonly_query`, `explain_query`, `get_safedb_policy`\n- Postgres support through `pg`\n- MySQL and MariaDB support through `mysql2`\n- SQLite file support through `sql.js`\n- YAML or JSON config with environment expansion\n- AST-backed read-only SQL guardrails for `SELECT`, `WITH ... SELECT`, `UNION`, and `EXPLAIN SELECT`\n- Table detection through joins, CTEs, nested subqueries, aliases, and unions\n- Column projection checks that block masked fields selected through aliases or expressions\n- Configurable table allowlists, denylists, row limits, and statement timeout\n- PII masking: `redact`, `email`, `partial`, and deterministic `hash`\n- JSONL audit log with no raw result data\n- CLI binary: `safedb-mcp`\n- TypeScript, Vitest, ESLint, Prettier\n\n## Quickstart\n\n```bash\nnpx @safedb/safedb-mcp init --output safedb.yaml\nDATABASE_URL=postgres://readonly:password@localhost:5432/app npx @safedb/safedb-mcp validate-config --config safedb.yaml\nDATABASE_URL=postgres://readonly:password@localhost:5432/app npx @safedb/safedb-mcp test-connection --config safedb.yaml\nDATABASE_URL=postgres://readonly:password@localhost:5432/app npx @safedb/safedb-mcp --config safedb.yaml\n```\n\nUse a dedicated database role with read-only permissions. SafeDB MCP is a defense-in-depth layer, not a replacement for least-privilege database credentials.\n\n## Docker\n\nA Docker image packages SafeDB MCP with Node.js and its production dependencies so it can run the same way on any host with Docker.\n\nBuild the image locally:\n\n```bash\ndocker build -t safedb-mcp .\n```\n\nRun the MCP server with a mounted config file:\n\n```bash\ndocker run --rm -i \\\n  -e DATABASE_URL=postgres://readonly:password@host.docker.internal:5432/app \\\n  -v \"$PWD/safedb.yaml:/config/safedb.yaml:ro\" \\\n  safedb-mcp\n```\n\nPass CLI commands after the image name:\n\n```bash\ndocker run --rm \\\n  -e DATABASE_URL=postgres://readonly:password@host.docker.internal:5432/app \\\n  -v \"$PWD/safedb.yaml:/config/safedb.yaml:ro\" \\\n  safedb-mcp --config /config/safedb.yaml validate-config\n```\n\n## Example Config\n\n```yaml\ndatabase:\n  type: postgres\n  url: ${DATABASE_URL}\n\nsafety:\n  default_limit: 100\n  max_limit: 1000\n  statement_timeout_ms: 5000\n  allow_explain: true\n\naccess:\n  schemas:\n    public:\n      allow_tables:\n        - users\n        - orders\n        - products\n      deny_tables:\n        - secrets\n      column_masks:\n        users.email: email\n        users.phone: partial\n        users.password_hash: redact\n        users.ssn: redact\n\naudit:\n  path: safedb-audit.jsonl\n```\n\nFor MySQL or MariaDB, set `database.type` and use the database name as the access schema:\n\n```yaml\ndatabase:\n  type: mysql\n  url: ${DATABASE_URL}\n\naccess:\n  schemas:\n    app:\n      allow_tables:\n        - users\n        - orders\n      deny_tables:\n        - secrets\n```\n\nFor SQLite, set `database.type` to `sqlite`, point `database.path` at the `.db` file, and use `main` as the access schema:\n\n```yaml\ndatabase:\n  type: sqlite\n  path: ./app.db\n\naccess:\n  schemas:\n    main:\n      allow_tables:\n        - users\n        - orders\n      deny_tables:\n        - secrets\n```\n\n## MCP Client Config\n\nClaude Desktop:\n\n```json\n{\n  \"mcpServers\": {\n    \"safedb\": {\n      \"command\": \"safedb-mcp\",\n      \"args\": [\"--config\", \"/absolute/path/to/safedb.yaml\"],\n      \"env\": {\n        \"DATABASE_URL\": \"postgres://readonly:password@localhost:5432/app\"\n      }\n    }\n  }\n}\n```\n\nCursor or Hermes-style MCP config:\n\n```json\n{\n  \"servers\": {\n    \"safedb\": {\n      \"command\": \"safedb-mcp\",\n      \"args\": [\"--config\", \"/absolute/path/to/safedb.yaml\"],\n      \"env\": {\n        \"DATABASE_URL\": \"postgres://readonly:password@localhost:5432/app\"\n      }\n    }\n  }\n}\n```\n\n## Security Guarantees\n\nSafeDB MCP aims to guarantee that:\n\n- Only configured schemas and tables are inspectable or queryable through the MCP tools.\n- SQL is parsed before execution, and mutating statement types or multiple statements are blocked.\n- Table access policy is checked against real tables found through joins, CTEs, nested subqueries, aliases, and unions.\n- Masked columns cannot be selected through aliases or expressions that would bypass response masking.\n- Query execution happens inside a read-only transaction with a local statement timeout where the driver supports it.\n- Returned rows are capped by an outer `LIMIT`.\n- Configured PII fields are masked before tool responses are returned.\n- Audit logs record attempts, decisions, detected tables, row counts, and duration without logging raw result rows.\n- Passwords and secrets are not intentionally logged.\n\n## Non-Goals\n\n- Formal proof of query safety.\n- Support for every valid dialect-specific read-only SQL construct.\n- Write operations, migrations, stored procedure execution, or `COPY`.\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpm test\nnpm run lint\n```\n\n## Roadmap\n\n- Per-tool and per-table rate limits.\n- Optional OpenTelemetry traces.\n- Signed audit logs.\n- Published Docker image and Helm chart.\n\n## License\n\nMIT\n",
  "bytes": 6328,
  "sha": "c67d4ff64d290f9e2abec6c917d2e95ae729d5d43dff2d2f8ad269e19e20d7df",
  "repo_slug": "narekmalk/safedb-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_narekmalk_safedb_mcp_07522baf/readme"
}