react-native-sqlite-mcp

Expose your React Native SQLite database to MCP-compatible tooling — with emulator support.

Overview

SQLite MCP servers exist, but they all assume your database is a file sitting on your desktop or server. They open a path, read the file, done.

That doesn't work for mobile. On iOS Simulator, SQLite databases are buried deep inside sandboxed app containers. On Android Emulator, they're behind run-as permission boundaries that require adb to access. No existing SQLite MCP server handles either of these.

I built this because I was tired of manually extracting .db files from emulators just to figure out why my app's local state was wrong.

react-native-sqlite-mcp is a SQLite MCP server purpose-built for mobile emulators. It auto-discovers databases inside iOS Simulator and Android Emulator sandboxes, pulls them transparently, and exposes schema + query access to any MCP-compatible tool.

Why This Exists

• Existing SQLite MCP servers can't reach databases inside iOS Simulator or Android Emulator sandboxes
• Mobile MCP tooling focuses on UI automation, not the data layer
• SQLite-backed state is critical in local-first React Native apps
• There was no MCP bridge for inspecting emulator databases directly from your AI tooling

This project fills that gap.

How It Works

graph LR
  subgraph Emulator
    RN[React Native App] --> SQLite[(SQLite DB)]
  end
  SQLite -- "simctl / adb pull" --> MCP[MCP Server]
  MCP -- "JSON-RPC stdio" --> AI[Claude / Cursor / Antigravity]

1. Auto-detects booted iOS Simulators (xcrun simctl) and Android Emulators (adb)
2. Discovers SQLite databases inside sandboxed app containers
3. Pulls database files transparently (iOS reads in-place, Android uses run-as + adb pull)
4. Exposes schema and query access over the MCP stdio transport

Quick Start

Add this to your MCP config (mcp.json, .cursor/mcp.json, or .gemini/settings.json):

{
  "mcpServers": {
    "rn-sqlite-bridge": {
      "command": "npx",
      "args": ["-y", "react-native-sqlite-mcp"],
      "env": {
        "DB_NAME": "my_app.db",
        "ANDROID_BUNDLE_ID": "com.mycompany.myapp"
      }
    }
  }
}

Restart your editor. Your AI can now query your emulator databases directly.

Environment Variables

| Variable | Required | Description | |---|---|---| | DB_NAME | No | Database filename to auto-sync on startup (e.g. my_app.db). Supports glob patterns (*.db). If omitted, auto-selects the first discovered database. | | ANDROID_BUNDLE_ID | No | Android app package name (e.g. com.mycompany.app). If omitted, scans all third-party packages on the emulator. | | READ_ONLY | No | Set to true to restrict query_db to SELECT, PRAGMA, and EXPLAIN statements only. Default: false. | | MCP_LOG_LEVEL | No | Log verbosity: debug, info, warn, error. Default: info. Logs go to stderr only. |

Tools

list_databases

Scans for all SQLite databases on booted emulators/simulators.

| Argument | Type | Description | |---|---|---| | platform | string | Optional. ios or android. If omitted, scans both. | | bundleId | string | Optional. Android-only app package name to narrow the search. |

sync_database

Pulls a fresh copy of the database from the emulator so all subsequent queries use the latest data.

| Argument | Type | Description | |---|---|---| | dbName | string | Optional. Database filename or glob pattern. Auto-selects if omitted. | | bundleId | string | Optional. Android-only app package name. | | platform | string | Optional. ios or android. |

inspect_schema

Returns all tables, columns, and CREATE TABLE statements for the synced database.

| Argument | Type | Description | |---|---|---| | dbName | string | Optional. Target a specific database. | | platform | string | Optional. ios or android. |

read_table_contents

Returns rows from a table (SELECT * FROM table LIMIT n).

| Argument | Type | Description | |---|---|---| | tableName | string | Required. The table to read. | | limit | number | Optional. Max rows to return. Default: 100. | | dbName | string | Optional. Target a specific database. | | platform | string | Optional. ios or android. |

query_db

Executes a raw SQL query and returns the result set.

| Argument | Type | Description | |---|---|---| | sql | string | Required. The SQL statement to execute. | | params | array | Optional. Bind parameters for ? placeholders. | | dbName | string | Optional. Target a specific database. | | platform | string | Optional. ios or android. |

When READ_ONLY=true, only SELECT, PRAGMA, and EXPLAIN statements are allowed.

Manual Installation

git clone https://github.com/MisterMur/react-native-sqlite-mcp.git
cd react-native-sqlite-mcp
npm install
npm run build

Point your MCP config at the local build:

{
  "mcpServers": {
    "rn-sqlite-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/react-native-sqlite-mcp/dist/index.js"],
      "env": {
        "DB_NAME": "my_app.db"
      }
    }
  }
}

Limitations

• Development environments only — not designed for production
• iOS requires a booted Simulator with xcrun simctl
• Android requires a booted Emulator with adb and a debuggable app (debug build)
• Queries operate on a pulled snapshot, not a live connection

Contributing

Issues and pull requests are welcome.

If you're working in the local-first React Native space and hit edge cases, open an issue. This tool exists because that gap was real.

License

MIT