JSON DB

You run a small, JSON-file backed MCP server that exposes a set of MCP tools alongside a REST API. It stores data in a single db.json file, supports atomic writes, and serves both MCP clients and REST clients through HTTP by default. This makes it easy to manage collections of items with generated identifiers while exposing familiar tool interfaces for automation and chat-based tooling.

How to use

You can interact with this server in two main ways: through MCP clients that talk the MCP protocol and through REST calls that manage data directly. The MCP tools give you programmatic access to add, read, list, update, and delete items in named collections. The REST API mirrors these capabilities, letting you create, read, update, list, and delete items via standard HTTP requests.

Start by running the server, then connect your MCP client or issue REST requests to manage items in a collection such as users. If you use the HTTP MCP transport, you will mount the MCP interface at /mcp/ and access the tools from there. If you prefer SSE, you can enable the SSE transport and connect to /mcp/sse/.

How to install

Prerequisites: Python 3.10 or newer, a local Python environment, and a terminal to run commands.

uv venv
uv pip install fastapi uvicorn fastmcp

Alternatively, you can create a virtual environment and install the dependencies with standard Python commands.

python -m venv .venv
source .venv/bin/activate
pip install fastapi uvicorn fastmcp

Running the server

To run in development mode with auto-reload, start the server with one of these commands.

uv run main.py
# or
uv run python main.py

Using the MCP HTTP transport

The default MCP transport is HTTP and is mounted at /mcp/. Use this path when configuring MCP clients or when enabling MCP in chat tools.

REST API quick start

All REST endpoints operate on a collection. A collection is created on first write and items have a unique id alongside your fields.

Create a new item in a collection called users: send a POST request to /db/users with your item payload.

List items in a collection: GET /db/users.

Get a specific item by ID: GET /db/users/{ITEM_ID}.

Update an item by ID: PUT /db/users/{ITEM_ID} with the partial payload you want to merge.

Delete an item by ID: DELETE /db/users/{ITEM_ID}.

Persistence and backups

Data is stored in a single file named db.json. Writes are atomic: a temporary file is written first, then the final file is atomically moved into place. Consider periodic backups or snapshots to protect data.

Health and troubleshooting

If you encounter issues, ensure you are accessing the MCP endpoint at /mcp/ for MCP interactions and /db/{collection} for REST. If you see redirects or 404s, trailing slashes often matter for certain transports. Run the server in a single process for file-backed storage to avoid concurrency conflicts.

Available tools

db.add_item

Add a new item to a named collection and receive the created item including its generated id.

db.get_item

Retrieve a single item by its id from a collection.

db.list_items

List all items within a collection.

db.update_item

Update fields of an existing item identified by its id.

db.delete_item

Delete an item by its id from a collection.