ajan-sql

<p align="center"> <img src="./assets/cover.svg" alt="ajan-sql cover" width="860" /> </p>

<p align="center"> <b>Safe, read-only SQL access for AI agents — via MCP.</b> </p>

<p align="center"> <a href="https://www.npmjs.com/package/ajan-sql"><img src="https://img.shields.io/npm/v/ajan-sql" /></a> <a href="https://www.npmjs.com/package/ajan-sql"><img src="https://img.shields.io/npm/dt/ajan-sql" /></a> <a href="https://borakilicoglu.github.io/ajan-sql/"><img src="https://img.shields.io/badge/docs-vitepress-5d98ea" /></a> <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-lightgrey" /></a> </p>

---

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