MCP User CRUD Server

A small test server that speaks MCP (Model Context Protocol). MCP is a standard way for AI assistants (like Claude) to call tools and get real data back, instead of just guessing answers.

This server manages a simple list of users (name, email, phone, age) stored in a plain JSON file. It's meant for testing and learning, not for storing real/production data.

What it can do

The server gives an AI assistant 5 tools it can call:

Tool	What it does
list_users	Show every user
search_user	Find users by any field (name, email, phone, age, id)
add_user	Create a new user
update_user	Change one or more fields on an existing user
delete_user	Remove a user

All the data lives in users_db.json, right next to the server script. You can open that file in any text editor to see or edit it directly.

Before you start

You need Python 3.10 or newer installed on your computer.

• Windows: download it from python.org
• Mac: run brew install python3 (or download from python.org)
• Linux: usually already installed; if not, sudo apt install python3 python3-venv (Ubuntu/Debian) or your distro's equivalent

You do not need to install anything else by hand — the launcher scripts below do that for you automatically the first time you run them.

How to run it

Pick the file that matches your computer. Everything else (installing dependencies, etc.) happens automatically.

• Windows → double-click run_server.bat
• Mac → double-click run_server_mac.command (if macOS blocks it the first time, right-click the file → Open → confirm)
• Linux → open a terminal in this folder and run bash run_server_linux.sh

The first time you run it, it may take a minute to set itself up. After that it starts instantly.

Choosing authentication

Every time you start the server, it asks how you want to protect it:

1. None         (no authentication)
2. API Key      (client sends X-API-Key header)
3. Bearer Token (client sends Authorization: Bearer <token> header)

• None — anyone who can reach the server can use it. Good for a quick local test.
• API Key — the server makes up a secret key (or you can type your own), and only requests that include that exact key are allowed in.
• Bearer Token — same idea as API Key, just using the Authorization: Bearer ... header style that a lot of tools expect.

Whichever you pick, the server prints the secret and a ready-to-use connection block right in the console — you don't need to remember or configure anything by hand.

Connecting to it

When the server starts, it prints something like this:

This machine  : http://127.0.0.1:8765/mcp
LAN / remote  : http://192.168.1.42:8765/mcp
Auth mode     : api_key
Secret        : Xy82jKf...

Client config (Claude Desktop / Claude Code / Cursor, etc.):
{
  "mcpServers": {
    "test-user-db": {
      "type": "streamable-http",
      "url": "http://192.168.1.42:8765/mcp",
      "headers": { "X-API-Key": "Xy82jKf..." }
    }
  }
}

Copy that JSON block into whichever MCP-compatible app you're connecting from (Claude Desktop, Claude Code, Cursor, etc.), and it will be able to see and use the 5 tools listed above.

• Use the 127.0.0.1 URL if the app is on the same computer as the server.
• Use the LAN / remote URL if you're connecting from a different computer on the same network.

Files in this folder

File	Purpose
start_server.py	The actual server code
users_db.json	The user data (plain JSON, safe to edit by hand)
run_server.bat	One-click launcher for Windows
run_server_mac.command	One-click launcher for Mac
run_server_linux.sh	Launcher for Linux
requirements.txt	List of Python packages the server needs
test_client.py	A script to test the server automatically (optional, not required to use the server)

Good to know

• This is a testing tool, not a production system. There's no encryption of the data file, and the API key / bearer token are simple shared secrets, not full user accounts.
• Stopping the server: just close the console window, or press Ctrl+C inside it.
• To clear all data, delete everything inside users_db.json and replace it with []. If the file is missing entirely, the server just starts with zero users and creates the file again as soon as you add one.