mcp-db-wrapper-example

The foro.sh database starter: an MCP server that wraps a small SQL database. It comes with one demo table (notes) so there's something to query straight away, and tools your AI coding agent can use to read and write it.

Opening this in Claude Code? Nothing to install. The repo ships the skills your agent needs in .claude/skills/: how to deploy this server, and how to add tools that are worth what they cost a model to carry.

Before you deploy

Without any setup, this runs on a local SQLite file that's wiped on every restart and redeploy - fine for trying it out, not for data you care about.

To keep data around, set DATABASE_URL as a secret in your project's Secrets tab (a sqlite:/// URL pointing at a file on a volume you control). For a different kind of database entirely, see Storage below.

Tools

Tool	What it does
list_tables()	See every table in the database
query(sql, params)	Run a read query (SELECT ...) and get the rows back
insert(table, values)	Add one row to a table

Make it yours

This is a starting point, not a finished product. Open this repo in Claude Code (or another AI coding agent) and ask it to:

• add the tables your project actually needs
• add tools for the specific things you want to do with your data — not just raw query/insert — e.g. find_customer(email), log_event(...)
• point it at a real database once you have one (see Storage below)

You don't need to know FastMCP or the Model Context Protocol to do any of this — describe what you want in plain language and let the agent write the code.

Storage

The database type is declared in pyproject.toml:

[tool.mcp-db-wrapper]
database = "sqlite"

server.py reads this and refuses to boot if DATABASE_URL doesn't match it (e.g. a non-sqlite:/// URL while database = "sqlite"), since the type is config, not something inferred from whatever URL happens to be set.

By default, with no DATABASE_URL secret, this runs on /tmp/db.sqlite3, created automatically, no setup required, and wiped on every restart and redeploy (the platform mounts no persistent volumes). Set DATABASE_URL to a sqlite:/// path on a volume you control to keep data around. For a different kind of database entirely (e.g. Postgres), ask your coding agent to swap in the matching driver and update database above to match.

Run it locally

uv run server.py

The server speaks MCP over streamable HTTP at http://localhost:8000/mcp (set PORT to change the port — the same name foro injects when it deploys you).

Deploy it

Its pyproject.toml is all foro.sh needs, so this repo deploys as-is: sign in, pick this repo, deploy.