GTD Server

A practical, self-learning Model Context Protocol (MCP) server tutorial built with Python, FastMCP, FastAPI, and Databricks Apps. The project implements a Getting Things Done assistant with typed MCP tools for tasks, projects, inbox capture, next actions, and statistics.

Run the same MCP server locally with Codex and SQLite, or deploy it as a custom Databricks App backed by a Unity Catalog Delta table and SQL warehouse. The server supports both stdio and Streamable HTTP at /mcp, and can be attached to Databricks AI Playground through its Tools panel.

What You Will Learn

• how to build an MCP server in Python with FastMCP,
• how MCP tools, schemas, transports, and structured responses work,
• how to connect a local MCP server to Codex,
• how to deploy an MCP server with Databricks Apps,
• how to use Databricks App resources, service-principal authentication, Unity Catalog, Delta tables, and a SQL warehouse,
• how to keep domain logic portable between SQLite and Databricks storage.

Start with QUICKSTART.md for setup and deployment. Use ARCHITECTURE.md as the complete workshop and extension guide.

Keywords: Model Context Protocol, MCP server, Python MCP, FastMCP, FastAPI, Databricks Apps, Databricks AI Playground, Codex MCP, Unity Catalog, Delta Lake, SQL Warehouse, AI agents, GTD assistant.

The operational code lives in src/; setup notebooks and client integration guides live in docs/.

Repository Map

gtd-mcp-server/
├── README.md                 # how to navigate and work with this repo
├── QUICKSTART.md             # local and Databricks Apps startup paths
├── ARCHITECTURE.md
├── LICENSE
├── pyproject.toml            # uv project metadata
├── uv.lock                   # locked local dependency set
├── src/                      # server package and Databricks app config
└── docs/
    ├── databricks_setup_storage.py
    ├── databricks_playground.md
    └── local_llm_ide.md

Local runs create a SQLite database at .local/gtd.sqlite3 by default. Databricks Apps use Delta storage.

Main Concepts

• src/gtd_mcp_server/server.py: FastMCP tools, FastAPI routes, launchers.
• src/gtd_mcp_server/storage.py: storage abstraction, SQLite backend, Delta backend.
• src/gtd_mcp_server/models.py: GTD task, project, inbox, and stats models.
• src/app.yaml: Databricks Apps startup command.
• src/requirements.txt: dependencies installed by Databricks Apps.
• pyproject.toml: local uv project metadata.
• uv.lock: locked local dependency set.
• docs/databricks_setup_storage.py: Databricks notebook that creates the Unity Catalog catalog, schema, and Delta table.
• docs/databricks_playground.md: how to attach the deployed app through the Playground Tools panel.
• docs/local_llm_ide.md: how to connect the local server to Codex.

Storage Modes

Local default:

GTD_STORAGE_BACKEND=sqlite
GTD_SQLITE_PATH=.local/gtd.sqlite3

Databricks Apps:

GTD_STORAGE_BACKEND=delta
GTD_DELTA_TABLE=gtd_mcp.app.gtd_mcp_records
DATABRICKS_WAREHOUSE_ID=<warehouse-id>
DATABRICKS_HOST=<injected-by-databricks-apps>

Before deployment, attach a SQL warehouse resource with key sql-warehouse and a UC table resource with key table. app.yaml maps both resources into environment variables with valueFrom; Databricks Apps injects DATABRICKS_HOST and service-principal credentials.

Before deploying on Databricks, run docs/databricks_setup_storage.py as a Databricks notebook. It creates the gtd_mcp catalog, app schema, and gtd_mcp_records Delta table used by the server.

When DATABRICKS_APP_NAME is present and GTD_STORAGE_BACKEND is unset, the server assumes delta.

Databricks Apps installs requirements.txt and starts the command from app.yaml:

uvicorn gtd_mcp_server.server:app --host 0.0.0.0 --port $DATABRICKS_APP_PORT

Daily Workflow

From this folder:

uv sync
uv run gtd-mcp-server

Then use:

• REST health check: http://localhost:8000/health
• MCP streamable HTTP endpoint: http://localhost:8000/mcp
• OpenAPI docs for the helper REST API: http://localhost:8000/docs

Use /mcp from an MCP client.