ajan-sql

⚡ What is ajan-sql?

ajan-sql is an MCP server that lets AI agents safely query your database.

👉 read-only
👉 schema-aware
👉 guardrailed

Supports:

• PostgreSQL

• MySQL

• SQLite

Related MCP server: mcp-multi-db

🚀 Quick Start

DATABASE_URL=postgres://USER:PASSWORD@HOST:PORT/DB npx ajan-sql

That’s it.

🧠 What it solves

AI agents querying databases is risky.

Without guardrails:

• they can modify data

• run heavy queries

• break your system

👉 ajan-sql fixes this by enforcing strict rules.

🔥 Safety by default

All queries are:

• SELECT only

• no INSERT, UPDATE, DELETE

• no DROP, ALTER, TRUNCATE

• limited results (LIMIT 100)

• timeout enforced (max 5s)

• no multi-statement queries

• no SQL comments

👉 These rules cannot be bypassed.

🔒 Sandboxing & Approvals

ajan-sql enforces sandboxing at the SQL access layer:

• every query is validated before execution

• query execution is readonly and bounded

• results are limited by row count, timeout, and size

• optional schema/table access policies can restrict readable tables

Human approval flows are handled by the MCP host or client. ajan-sql does not provide its own approval UI.

For production use, connect with a database user that only has readonly permissions. Database permissions should be the final safety backstop.

⚡ Available Tools

• list_tables

• describe_table

• list_relationships

• search_schema

• run_readonly_query

• explain_query

• sample_rows

• server_info

🧠 Example

{
  "tool": "run_readonly_query",
  "arguments": {
    "sql": "SELECT * FROM users LIMIT 10"
  }
}

Tool responses include both standard MCP structuredContent and an embedded text/toon version of the same payload.

🌐 Supported Databases

# PostgreSQL
DATABASE_DIALECT=postgres
DATABASE_URL=postgres://USER:PASSWORD@HOST:PORT/DB

# MySQL
DATABASE_DIALECT=mysql
DATABASE_URL=mysql://USER:PASSWORD@HOST:PORT/DB

# SQLite
DATABASE_DIALECT=sqlite
DATABASE_URL=file:/absolute/path/to/database.sqlite

Optional readonly policy controls:

AJAN_SQL_ALLOWED_SCHEMAS=public,analytics
AJAN_SQL_ALLOWED_TABLES=public.users,analytics.events
AJAN_SQL_DENIED_TABLES=public.audit_logs
AJAN_SQL_AUDIT_LOG=true

⚙️ Features

• MCP-native SQL access

• multi-database support

• strict read-only guardrails

• schema discovery + introspection

• structured JSON output for AI agents

• TOON-formatted embedded tool results

• predictable execution limits

• type-safe schemas

🧠 Use Cases

• AI copilots querying databases

• internal data assistants

• analytics agents

• safe DB access in automation

• MCP-based workflows

📦 Install

npm install -g ajan-sql

or:

npx ajan-sql

🧩 Client Example

{
  "mcpServers": {
    "ajan-sql": {
      "command": "npx",
      "args": ["ajan-sql"],
      "env": {
        "DATABASE_DIALECT": "postgres",
        "DATABASE_URL": "postgres://USER:PASSWORD@HOST:PORT/DB"
      }
    }
  }
}

💡 Philosophy

AI should never have unsafe database access.

ajan-sql ensures queries are safe, predictable, and controlled.

❤️ Support

If this tool helps you:

⭐ Star the repo
☕ Support via GitHub Sponsors

https://github.com/sponsors/borakilicoglu

🔗 Links

• GitHub: https://github.com/borakilicoglu/ajan-sql

• npm: https://www.npmjs.com/package/ajan-sql

• Docs: https://borakilicoglu.github.io/ajan-sql/