⚡ 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

🚀 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/