数据库管理 MCP 服务

instant-db

An MCP server that lets any connected AI assistant create and manage structured databases through natural language alone. No SQL. No schema files. Just describe what you want to track and start using it.

Runtime: Bun · Language: TypeScript · Storage: SQLite (via bun:sqlite)

What It Does

"I want to track my workouts — exercises, sets, reps, and weights."

Claude calls the MCP server, proposes a schema in plain English, waits for your confirmation, creates the database, and from that point on handles all inserts, queries, updates, and deletes — across sessions, persistently.

Setup (under 10 minutes)

1. Clone and install

git clone https://github.com/your-username/instant-db
cd instant-db
bun install

2. Configure environment

cp .env.example .env
# Edit .env if you want custom paths (defaults work fine)

3. Add to Claude Desktop

Edit your claude_desktop_config.json (usually at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "instant-db": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/instant-db/src/index.ts"],
      "env": {
        "DATA_DIR": "/absolute/path/to/instant-db/data",
        "LOG_LEVEL": "normal"
      }
    }
  }
}

Replace /absolute/path/to/instant-db with the actual path where you cloned the repo.

4. Restart Claude Desktop

The instant-db tools will appear in Claude's tool list. You're done.

Usage

Start a new database

"I want to track my workouts — exercises, sets, reps, and weights."

Claude will propose a schema, you refine it in plain English, then confirm. The database is created.

Use it

"Log today's workout — 3 sets of 8 squats at 185 lbs." "How much did I squat last week?" "What's my heaviest bench press ever?"

Data persists across sessions automatically.

Recommended System Prompt

Add this to your Claude system prompt for best results:

You have access to an instant-db MCP server for persistent structured storage.
When a user wants to track or store anything:
1. Call list_databases first to check what already exists.
2. If no relevant database exists, call propose_schema and present the proposal
   conversationally — don't dump JSON at the user.
3. Wait for explicit user confirmation before calling create_database.
4. Always call describe_database at the start of a new session before inserting
   or querying, so you know the current schema.

MCP Tools Reference

Debugging

Every MCP tool call is logged to logs/mcp.log in JSONL format.

# Live tail with pretty output
tail -f logs/mcp.log | jq .

Log level is controlled by the LOG_LEVEL env var: verbose | normal | off

SQLite files are standard — open them in DB Browser for SQLite or any SQLite tool.

Configuration

All config via .env:

DATA_DIR=./data          # Where .sqlite files are stored
LOG_LEVEL=normal         # verbose | normal | off
LOG_PATH=./logs/mcp.log  # Log file location
MCP_TRANSPORT=stdio      # Always stdio for Claude Desktop

Development

# Run tests
bun test

# Run the server directly (for debugging)
bun run src/index.ts

Fly.io status

Fly deployment scaffolding exists in:

• Dockerfile
• .dockerignore
• fly.toml.example
• docs/fly-deployment.md

The repo now includes streamable HTTP transport plus protected-resource metadata / bearer-token auth hooks for remote MCP. The remaining hosted-MVP work is deploying with real OAuth issuer settings, validating against a real WorkOS setup, and confirming the end-to-end Claude-compatible flow.

Headless clients (personal access tokens)

An agent that can't complete a browser login can authenticate to the hosted /mcp endpoint with a personal access token instead. A token acts as your user, so it sees the same databases as your OAuth session, and its tool calls count against your usage.

1. Find your user id. Sign in to the dashboard and open /api/me. The sub field is your user id.

2. Mint a token on the host that holds the data directory:

fly ssh console -C "bun run scripts/pat.ts create --sub <your-sub> --name labmind-pi --expires-days 90"

The token (mcpdb_pat_…) is printed once. Only its sha256 hash is stored, so copy it now. Leave off --expires-days for a token that doesn't expire.

3. Configure the client to send it as a bearer token:

{
  "mcpServers": {
    "instant-db": {
      "type": "http",
      "url": "https://<your-host>/mcp",
      "headers": { "Authorization": "Bearer mcpdb_pat_…" }
    }
  }
}

List or revoke tokens:

bun run scripts/pat.ts list   --sub <your-sub>
bun run scripts/pat.ts revoke --sub <your-sub> --id <token-id>

A revoked or expired token gets a 401.

Architecture

If you want the short explanation of how local mode, hosted mode, auth, and storage fit together, read:

• docs/architecture.md

It includes a plain-English walkthrough and an ASCII diagram of the full stack.

Repository Structure

src/
  index.ts          # Entry point
  server.ts         # MCP server setup, tool registration
  config.ts         # Env var loading (Zod-validated)
  logger.ts         # JSONL request/response logger
  tools/
    database.ts     # list_databases, describe_database
    schema.ts       # propose_schema, create_database
    records.ts      # insert, query, update, delete, count
  db/
    adapter.ts      # IDbAdapter interface
    sqlite.ts       # SQLite implementation
    registry.ts     # Multi-database manager
data/               # SQLite files (gitignored)
logs/               # MCP logs (gitignored)

Multiple Databases

One server instance manages as many named databases as you want:

"Create a calories tracker" "Create a finances tracker" "List my databases" → ["workouts", "calories", "finances"]

Each database is a separate .sqlite file in data/.

What's Not in MVP

• Schema migrations (add/rename columns after creation)
• Joins / cross-table queries
• Batch insert
• Data export (CSV, JSON)
• Web UI (use any SQLite browser directly)
• Postgres adapter (interface ready, implementation deferred)
• Auth / access control

License

MIT