mcp-starter

A minimal MCP (Model Context Protocol) server that demonstrates the three core capability types — Tools, Resources, and Prompts — through a simple notes app.

Use this as a learning template or starting point for building your own MCP server.

What's inside

Notes are persisted to notes.json alongside server.py.

Install

One-liner (bash)

Requires uv and Claude Code.

curl -fsSL https://raw.githubusercontent.com/ejoliet/mcp-starter/main/install.sh | bash

This clones the repo to ~/mcp-starter, installs dependencies, and registers the server with Claude Code automatically. Start a new Claude Code session and it's ready.

To install to a custom path:

MCP_STARTER_DIR=~/dev/mcp-starter curl -fsSL https://raw.githubusercontent.com/ejoliet/mcp-starter/main/install.sh | bash

Docker

Requires Docker.

git clone https://github.com/ejoliet/mcp-starter.git
cd mcp-starter
docker compose up --build

Notes are persisted in a named Docker volume (notes-data). Register the containerized server with Claude Code:

claude mcp add mcp-starter -- docker compose -f ~/mcp-starter/docker-compose.yml run --rm mcp-starter

Manual setup

Requirements: Python 3.12+, uv, Claude Code.

git clone https://github.com/ejoliet/mcp-starter.git ~/mcp-starter
cd ~/mcp-starter
uv sync
claude mcp add mcp-starter -- uv --directory ~/mcp-starter run server.py

Then start a new Claude Code session — the server will be available automatically.

Usage in Claude

Once registered, Claude can call tools directly:

"Add a note titled 'standup' with body 'review PR #42'"
"List my notes"
"Delete note #1"

Or read the resource and prompt via the MCP panel (/mcp).

CLI development & testing

See DEV_GUIDE.md for how to iterate on the server from the terminal without relying on Claude Code.

Quick test:

uv run python test_resource.py

Project structure

mcp-starter/
├── server.py          # MCP server implementation
├── test_resource.py   # CLI test harness
├── install.sh         # Bash one-liner installer
├── Dockerfile         # Container image
├── docker-compose.yml # Compose config
├── pyproject.toml     # Dependencies
└── DEV_GUIDE.md       # Developer iteration guide

Extending

Add a new tool in server.py:

1. Append a types.Tool(...) entry in list_tools()

2. Handle name == "your_tool" in call_tool()

3. Test with test_resource.py before restarting Claude Code