AxioDB is an embedded NoSQL database for Node.js with MongoDB-style queries. It is a pure JavaScript alternative to SQLite with zero native dependencies, no node-gyp compilation, and no platform-specific binaries. Install with 'npm install axiodb' and you have a database — no mongod process, no server setup. Perfect for Electron apps, CLI tools, and local-first applications.

Is AxioDB a replacement for MongoDB?

No. AxioDB is embedded — it runs inside your app with no server. MongoDB is a client-server database for multi-user production systems. Use AxioDB for desktop apps, CLI tools, and local-first applications with 10K–500K documents. Use MongoDB when you need a shared, networked, multi-user database.

Does AxioDB work with Electron?

Yes — Electron is the primary use case AxioDB was built for. Zero native dependencies means no electron-rebuild, no platform-specific .node files, no node-gyp compilation. Just npm install axiodb and it works on Windows, Mac, and Linux without any rebuild step.

What is the difference between AxioDB and better-sqlite3?

better-sqlite3 uses C native bindings and requires compilation via node-gyp. AxioDB is pure JavaScript — it installs in any Node.js environment without compilation or platform-specific builds. AxioDB also uses NoSQL/JSON document queries instead of SQL strings, includes built-in caching and Worker Threads, and works out of the box in Electron without electron-rebuild.

What is the difference between AxioDB and lowdb?

lowdb stores everything in a single JSON file and becomes slow above 1,000–5,000 records due to full-file reads on every operation. AxioDB uses file-per-document tree storage with InMemoryCache, Worker Threads, and auto-indexing — optimized for 10,000–500,000 documents with O(1) lookups by ID and fast filtered queries.

What is the difference between AxioDB and nedb?

NeDB is abandoned (no active maintenance since 2016) and keeps the entire database in memory. AxioDB is actively maintained, uses file-based storage, supports TypeScript, ACID transactions with savepoints and WAL, Worker Threads, custom field indexing, and AxioDBCloud remote access.

How many documents can AxioDB handle?

AxioDB is optimized for 10,000–500,000 documents per collection. For 1M+ documents, migrate to PostgreSQL or MongoDB. AxioDB's InMemoryCache and Worker Threads keep performance fast within this range — documentId lookups take ~1ms and indexed queries take ~2ms on 10,000 documents.

Does AxioDB support TypeScript?

Yes. Full TypeScript type definitions are included out of the box with the axiodb npm package. No @types/axiodb needed.

Does AxioDB work in the browser?

No. AxioDB requires Node.js (v20+) and uses the filesystem for storage. It is a server-side and desktop embedded database. It does not run in browsers.

AxioDBCloud is AxioDB's own TCP remote-access layer on port 27019 — a protocol and client, not a hosted service. You run the server yourself with new AxioDB({ TCP: true }) or the Docker image, then connect from other processes using the exact same API as embedded AxioDB, with zero code changes. There is no account to create and Nexoral hosts no database for you. Limits: 1,000 total concurrent connections, 100 per IP. Optional shared-RBAC authentication (TCPAuth) and optional TLS.

How do I replace SQLite with AxioDB in a Node.js project?

Install with 'npm install axiodb' and map concepts directly: a SQLite table becomes a collection, a row becomes a JSON document, INTEGER PRIMARY KEY becomes the auto-generated documentId, CREATE INDEX becomes collection.newIndex('field'), and BEGIN/COMMIT/ROLLBACK become collection.beginTransaction()/.commit()/.rollback(). SQL strings become JavaScript objects: SELECT * FROM users WHERE age > 25 becomes users.query({ age: { $gt: 25 } }).exec(). There are no schemas and no migrations. What you give up: JOINs, foreign keys, SQL itself, ORMs like Prisma and Drizzle, and scale beyond roughly 500,000 documents per collection.

Does AxioDB need node-gyp, electron-rebuild, or a build step?

No. AxioDB is pure JavaScript with zero native dependencies — there is no C code, no .node binary, no node-gyp compilation, and no electron-rebuild step. Nothing has to match your OS, CPU architecture, or Node/Electron ABI version, so NODE_MODULE_VERSION mismatch errors are impossible. 'npm install axiodb' is the entire installation on every platform and every Node.js version 20 or newer.

How do I use AxioDB in an Electron app?

Create the AxioDB instance in Electron's main process only, storing data in the per-user data directory: new AxioDB({ RootName: 'AppData', CustomPath: app.getPath('userData'), GUI: false }). Never write inside the app bundle or app.asar — asar is read-only and app contents are replaced on update. Expose database operations to the renderer through ipcMain.handle plus contextBridge rather than enabling nodeIntegration. No electron-rebuild step and no packaging configuration for native modules is required.

Does AxioDB have an MCP server for AI agents?

Yes — 32 MCP tools covering databases, collections, documents, aggregation, indexes, dashboard stats, and user/role management. Important: the MCP server ships only in the Docker image theankansaha/axiodb, not in the npm package. Enable it with AXIODB_MCP=true and connect over Streamable HTTP at http://localhost:27020/mcp. Every tool except axiodb_login requires a sessionId from logging in, and destructive tools ask the human for confirmation through the MCP client first.

What ports does AxioDB use?

Port 27018 is the web Dashboard and its REST HTTP API, enabled with GUI: true. Port 27019 is the AxioDBCloud TCP server, enabled with TCP: true — it is a custom TCP protocol, not HTTP. Port 27020 is the MCP server, available only in the Docker image with AXIODB_MCP=true. Ports 27018 and 27019 are not configurable in code; remap them at the Docker layer. Only the MCP port can be changed, via AXIODB_MCP_PORT. By default the embedded library opens no ports at all.

Does AxioDB support MongoDB update operators like $inc and $set?

No. AxioDB updates are a flat shallow merge of your data object onto the existing document. Writing .UpdateOne({ $inc: { balance: -100 } }) does not increment anything — it literally stores a field named '$inc'. To change a numeric value, read the document, compute the new value in JavaScript, and write it back. Query operators are a separate thing and are fully supported: $gt, $gte, $lt, $lte, $eq, $ne, $in, $nin, $exists, $regex, $not, $type, $size, $all, $elemMatch, $or, $and, and $nor.

What are AxioDB's limitations?

AxioDB targets 10,000 to 500,000 documents per collection on a single node. It has no JOINs, no foreign keys, no SQL, no replication, no sharding, and no clustering. Transactions are scoped to one collection — there are no cross-collection transactions. Only one AxioDB instance may exist per process. Aggregation supports only $sum and $avg accumulators, and its $match stage accepts fewer operators than query() does. Queries that are not an exact match on an indexed field fall back to a full collection scan. It does not run in browsers.

AI AGENT INTEGRATION

MCP Server

Spin up AxioDB in a container and let Claude (or any MCP-compatible AI agent) talk to it directly — create databases, query documents, run aggregations, manage users and roles, all through 32 tools that log in and enforce the exact same RBAC as the web GUI. It runs in the same process as your existing Docker deployment — no separate install, no new database instance.

Quick Start

The MCP server is opt-in and disabled by default — set AXIODB_MCP=true on the same container you already run for the GUI/TCP server:

bash

1docker run -d \
2  --name axiodb-server \
3  -e AXIODB_GUI=true \
4  -e AXIODB_MCP=true \
5  -p 27018:27018 \
6  -p 27019:27019 \
7  -p 27020:27020 \
8  -v axiodb-data:/app \
9  theankansaha/axiodb
10
11# Ports:
12# 27018 - HTTP GUI Dashboard
13# 27019 - TCP Remote Access (AxioDBCloud)
14# 27020 - MCP Server (Streamable HTTP, path /mcp)

Claude Code

bash

1claude mcp add --transport http axiodb http://localhost:27020/mcp
2
3# Available across every project instead of just this one:
4claude mcp add --transport http axiodb http://localhost:27020/mcp -s user

OpenAI Codex CLI

bash

1codex mcp add axiodb --url http://localhost:27020/mcp
2
3# Or edit ~/.codex/config.toml directly:
4[mcp_servers.axiodb]
5url = "http://localhost:27020/mcp"

opencode

bash

1opencode mcp add
2# Interactive prompt: choose "remote", name it "axiodb",
3# URL: http://localhost:27020/mcp
4
5# Or edit opencode.json directly:
6{
7  "mcp": {
8    "axiodb": {
9      "type": "remote",
10      "url": "http://localhost:27020/mcp",
11      "enabled": true
12    }
13  }
14}

GitHub Copilot CLI

bash

1# Interactive: run copilot, then inside it type:
2/mcp add
3# Server Name: axiodb | Type: HTTP | URL: http://localhost:27020/mcp
4
5# Or edit ~/.copilot/mcp-config.json directly:
6{
7  "mcpServers": {
8    "axiodb": {
9      "type": "http",
10      "url": "http://localhost:27020/mcp"
11    }
12  }
13}

Cursor

json

1// .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
2{
3  "mcpServers": {
4    "axiodb": {
5      "url": "http://localhost:27020/mcp"
6    }
7  }
8}

Windsurf

json

1// ~/.codeium/windsurf/mcp_config.json
2{
3  "mcpServers": {
4    "axiodb": {
5      "serverUrl": "http://localhost:27020/mcp"
6    }
7  }
8}

Google Antigravity (IDE & CLI)

json

1// ~/.gemini/config/mcp_config.json - note: serverUrl, not url
2{
3  "mcpServers": {
4    "axiodb": {
5      "serverUrl": "http://localhost:27020/mcp"
6    }
7  }
8}

AXIODB_MCP=true only has something to serve once RBAC is actually seeded — that requires AXIODB_GUI=true (the default) or AXIODB_TCP=true + AXIODB_TCP_AUTH=true. See Docker Deployment for every environment variable.

Real Login, Real RBAC — Not a Docker Env Var

Every tool except axiodb_login requires a sessionId. Call axiodb_login first with the seeded default account (admin/admin, same as the GUI) or any other RBAC user, and every subsequent call is checked against that logged-in user's actual role — a View-role session gets a real 403 on write tools, exactly like the GUI would. Nothing is gated by a static container environment variable.

json

1// axiodb_login({ username: "admin", password: "admin" })
2{
3  "statusCode": 200,
4  "message": "Login successful",
5  "data": {
6    "sessionId": "a1b2c3...",
7    "username": "admin",
8    "role": "Super Admin",
9    "permissions": ["db:view", "db:create", "..."],
10    "mustChangePassword": true
11  }
12}

Sessions live in server memory only, 24h sliding TTL — call axiodb_logout when done rather than waiting it out
axiodb_whoami returns the identity/role/permissions behind a given session
axiodb_change_own_password rotates the session and returns a new sessionId
Same login rate limiter as the GUI/TCP login (5 failed attempts / 15 min lockout)

32 Tools, Mirroring the HTTP Control Server 1:1

Every MCP tool maps to the exact same controller and permission check as its HTTP route counterpart — nothing was reimplemented, so behavior (validation, error messages, RBAC) never drifts between the GUI and the MCP surface.

Session

No permission required — login is the gate itself

axiodb_login
axiodb_logout
axiodb_whoami
axiodb_change_own_password

Database

db:view / db:create / db:delete

axiodb_create_database
axiodb_delete_database
axiodb_database_exists
axiodb_get_instance_info

Collection

collection:view / collection:create / collection:delete

axiodb_create_collection
axiodb_delete_collection
axiodb_collection_exists
axiodb_get_collection_info

Documents & Aggregation

document:view / query / create / update / delete / aggregate

axiodb_insert_document
axiodb_insert_many_documents
axiodb_query_documents
axiodb_update_document
axiodb_delete_document
axiodb_total_documents
axiodb_aggregate

Index

index:view / index:create / index:delete

axiodb_create_index
axiodb_drop_index
axiodb_list_indexes

Dashboard

dashboard:view

axiodb_get_dashboard_stats

User Management

user:view / create / update-role / reset-password / delete — Super Admin role only

axiodb_list_users
axiodb_create_user
axiodb_update_user_role
axiodb_reset_user_password
axiodb_delete_user

Role Management

role:view / role:create / role:delete — Super Admin role only

axiodb_list_roles
axiodb_create_role
axiodb_delete_role
axiodb_list_permissions

Out of scope by design: transactions and database export/import are not exposed as MCP tools — kept out of this surface entirely rather than deferred.

Human in the Loop on Destructive Tools

Nine tools destroy or overwrite existing state, and each one asks a human before it runs — through your MCP client's own confirmation prompt (the protocol's elicitation/create request), naming the exact target. Declining, cancelling, or leaving the box unchecked aborts with 409 and the operation never reaches the database. Inserts, creates and index builds are never prompted — they only ever add.

text

1Agent: axiodb_delete_collection({ sessionId, dbName: "shop", collectionName: "orders" })
2
3  -> your MCP client prompts YOU:
4     "Delete the collection "orders" from database "shop"? Every document and
5      index inside it is permanently removed. This cannot be undone."   [ ] Confirm
6
7  Declined ->  { "statusCode": 409, "message": "Aborted: this destructive operation
8                  was not confirmed by a human reviewer." }
9  Confirmed -> collection deleted

Tool	Prompted because
axiodb_delete_database	drops every collection, document and index inside it
axiodb_delete_collection	drops every document and index inside it
axiodb_delete_document	irreversible; many: true deletes every match
axiodb_update_document	overwrites unrecoverable field values; many: true hits every match
axiodb_drop_index	queries fall back to full scans until it is rebuilt
axiodb_delete_user	removes the account and all of its sessions
axiodb_delete_role	removes the role's permission set
axiodb_update_user_role	changes what that account may do across GUI, TCP and MCP
axiodb_reset_user_password	invalidates the current password and every session

Annotations, and the one hard guarantee: every tool also ships MCP annotations (readOnlyHint, destructiveHint, idempotentHint) so clients can auto-approve reads while holding writes for review. A client that doesn't support elicitation can't show the prompt, and the call then proceeds on the annotations alone — so for an agent that must never write, hand it a View-role login: that is enforced server-side in RBAC and needs no client cooperation.

Example: Insert & Query From an Agent

text

11. axiodb_login({ username: "admin", password: "admin" })
2   -> sessionId: "a1b2c3..."
3
42. axiodb_create_database({ sessionId, name: "shop" })
5
63. axiodb_create_collection({ sessionId, dbName: "shop", collectionName: "orders" })
7
84. axiodb_insert_document({
9     sessionId, dbName: "shop", collectionName: "orders",
10     document: { customer: "Alice", total: 49.99, status: "paid" }
11   })
12
135. axiodb_query_documents({
14     sessionId, dbName: "shop", collectionName: "orders",
15     query: { status: "paid" }
16   })

Security Notes

Every write/read tool is permission-checked against the caller's actual role on every call, not just at login
An invalid, expired, or missing sessionId is rejected before it ever reaches a database operation
The nine destructive tools require an explicit human confirmation through the client before they touch data — see Human in the Loop above; a View-role login is the server-side way to make an agent read-only
Expose port 27020 only to trusted networks/agents, same guidance as the TCP port — the MCP server carries the same authority as the GUI, just a different transport

Give Your Agent a Database

Deploy the container, enable AXIODB_MCP, and register it with your MCP client.

Docker Deployment Docker/README.md Security & RBAC