TODO MCP Server for Claude (Python)
Simple TODO MCP server implemented in Python using the official mcp SDK. It exposes MCP tools over HTTP so Claude web can add, list, and remove TODOs, storing data in a local JSON file.
Features
- Python MCP server using
mcp.server.fastmcp.FastMCP - Tools:
add_todo_item(text: str)– add a TODOlist_todo_items()– list all TODOsremove_todo_item(todo_id: str)– remove by id- Storage: JSON file on disk with file locking (
filelock) - Transports: Streamable HTTP at
/mcp(port 8000 by default) - Auth modes (config-only for now):
AUTH_MODE=none– no auth (local-only)AUTH_MODE=api_key– static API key via HTTP headerAUTH_MODE=cognito– AWS Cognito JWT validation helpers
> Note: The MCP Python SDK’s HTTP transport currently does not expose HTTP headers directly to tool handlers. The auth.py module provides reusable functions to validate API keys and Cognito JWTs, which you can plug into HTTP middleware once the SDK exposes hooks, or via a reverse proxy that terminates auth before forwarding to /mcp.
Repository structure
Single source of truth at repo root; no duplicated app code.
- server.py – MCP app + HTTP entrypoint (CORS, streamable-http).
- server_stdio.py – Stdio entrypoint for Claude Desktop / .mcpb.
- config.py, todo_store.py, auth.py – Config, storage, auth helpers.
- mcpb/ – Bundle-only files:
manifest.json,data/.gitkeep. See mcpb/README.md. - scripts/build-mcpb.sh – Builds
todo-mcp.mcpbfrom root + mcpb (run from project root).
1. Install dependencies (local dev)
From the project root:```bash
python -m venv .venv
source .venv/bin/activate # on Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt
### 2. Run the MCP server locally
By default this will:
- Listen on `0.0.0.0:8000`
- Store todos in `./data/todos.json`
- Use `AUTH_MODE=api_key` (but not yet enforced at HTTP level)```bash
export MCP_PORT=8000
export TODO_FILE_PATH=./data/todos.json
export AUTH_MODE=none # for local testing
python server.py
You should see the server start without errors.
Test with MCP Inspector (optional)
In another terminal:```bash
npx -y @modelcontextprotocol/inspector
Connect to:```text
http://localhost:8000/mcp
You should see the tools:
add_todo_itemlist_todo_itemsremove_todo_item
3. Docker build and run (local)
Build the image:```bash
docker build -t todo-mcp:local .
Run it with a mounted `data` directory:```bash
mkdir -p data
docker run \
-p 8000:8000 \
-e MCP_PORT=8000 \
-e TODO_FILE_PATH=/app/data/todos.json \
-e AUTH_MODE=none \
-v "$(pwd)/data:/app/data" \
todo-mcp:local
Or use docker-compose:```bash
docker compose up --build
Then connect MCP Inspector to `http://localhost:8000/mcp` as above.
---
### 4. Claude Desktop (.mcpb)
To install as a one-click extension in Claude Desktop:
1. Build the bundle from project root: `./scripts/build-mcpb.sh`
2. Double-click the generated **todo-mcp.mcpb** and approve in Claude Desktop.
3. Restart Claude Desktop if needed. See mcpb/README.md for details.
---
### 5. Deploy to AWS Lightsail (Docker on a VM)
1. **Create Lightsail instance**
- Choose a small Linux instance (Ubuntu) in your preferred region.
- Enable SSH.
- In “Networking”, open:
- TCP **22** (SSH)
- TCP **8000** (or 80/443 if you put a reverse proxy in front)
2. **Install Docker on the instance**
SSH into the instance:```bash
sudo apt-get update
sudo apt-get install -y docker.io docker-compose-plugin
sudo usermod -aG docker "$USER"
# log out and back in to apply group changes
```
3. **Get the code onto the instance**
Options:
- `git clone` your repo, or
- `scp` this folder up, or
- push the Docker image to a registry (Docker Hub/ECR) and `docker pull` on Lightsail.
Example with direct build on the instance:```bash
cd ~/mcp-todo
docker build -t todo-mcp:prod .
mkdir -p data
docker run -d \
--name todo-mcp \
-p 8000:8000 \
-e MCP_PORT=8000 \
-e TODO_FILE_PATH=/app/data/todos.json \
-e AUTH_MODE=none \
-v "$PWD/data:/app/data" \
todo-mcp:prod
```
4. **(Optional) Add HTTPS and Cognito in front**
For production, you typically:
- Put an HTTPS load balancer or Nginx reverse proxy in front of the container.
- Configure AWS Cognito (or AWS ALB with Cognito auth) to protect the `/mcp` endpoint.
- Forward only authenticated traffic to the MCP server.
`auth.py` already contains helpers (`verify_api_key`, `verify_cognito_jwt`, `authenticate_from_headers`) that you can use in a future HTTP middleware layer once the MCP HTTP transport exposes headers, or from a sidecar API gateway/proxy.
---
### 6. Connect from Claude (HTTP MCP)
Once the server is reachable from the public internet (for example):```text
http://YOUR_LIGHTSAIL_IP:8000/mcp
Add an HTTP MCP server in Claude web / Claude Code with:
- Transport: HTTP
- URL:
http://YOUR_LIGHTSAIL_IP:8000/mcp(orhttps://your-domain/mcpif behind HTTPS) - Headers:
- For now, you can leave empty while
AUTH_MODE=none. - Later, once you front it with Cognito or API Gateway, you will typically add:
Authorization: BearerorX-API-Key:
After saving, Claude should:
- Discover the TODO tools.
- Let you run
add_todo_item,list_todo_items, andremove_todo_itemdirectly from chat.
7. AWS Cognito integration (conceptual)
To integrate Cognito as you evolve this project:
-
Create Cognito User Pool and App Client
- Note the User Pool ID and Region.
- Create an App Client (no client secret), note its Client ID. -
Set environment variables on Lightsail
bash export AUTH_MODE=cognito export COGNITO_REGION=your-region export COGNITO_USER_POOL_ID=your-pool-id export COGNITO_APP_CLIENT_ID=your-app-client-id -
Obtain a JWT token
- Use AWS CLI (aws cognito-idp initiate-auth) or a small helper app to log in and obtain an ID or access token. -
Configure your front-end/auth proxy
- Ensure it sendsAuthorization: Bearerto your MCP server.
- Theauth.pyhelpers show how to validate those tokens on the server side once HTTP headers are available.
8. Notes and next steps
- This is intentionally minimal and file-based. For more serious use:
- Move storage to a database (e.g. DynamoDB, PostgreSQL).
- Add structured logging and monitoring.
- Harden network access (firewalls, IP allow-lists, stricter auth).
- You can now iterate on additional tools (e.g. mark TODO as done, filter by user, etc.) by adding more decorated functions in
server.py.
