Things 3 GTD MCP Server

A Model Context Protocol (MCP) server for Things 3 that brings Getting Things Done (GTD) methodology to AI assistants. macOS only.

What it is

This server exposes Things 3 to AI assistants (Claude Desktop, Claude Code, Claude Mobile, ChatGPT, n8n, Cursor, OpenClaw) over MCP. The tools are organized around David Allen's five GTD stages — Capture, Clarify, Organize, Reflect, Engage — so an assistant can help you practice GTD, not just CRUD a task database.

The shift from "database wrapper" to "GTD assistant" reflects a key insight about MCP design: tools should match how agents think about problems, not how the underlying APIs are structured.

Requirements

Installation

pip install things3-mcp-gtd
# or, no install:
uvx things3-mcp-gtd

For a local development install, see docs/DEVELOPERS.md.

Review the Privacy Notice and Terms of Use before running the server.

Configuration

Copy .env.example to .env and set at minimum:

THINGS_AUTH_TOKEN=<paste from Things -> Settings -> General -> Enable Things URLs>

The server reads from environment variables and the .env file via pydantic-settings. All other settings (host, port, debug, auth enforcement) have sensible defaults — see .env.example for the full list.

Alternatively, run the interactive helper:

python scripts/configure_token.py

which writes the token to ~/.things-mcp/config.json.

Quick start

Make sure Things 3 is open, then:

# If installed via pip or uvx
things3-mcp-gtd

# If running from source
uv run server

The server binds to localhost:8009 by default with a single MCP endpoint at /mcp over streamable HTTP.

Connecting an MCP client

Claude Desktop (stdio)

~/Library/Application Support/Claude/claude_desktop_config.json:

If installed via pip:

{
  "mcpServers": {
    "things3-gtd": {
      "command": "things3-mcp-gtd"
    }
  }
}

If running from source:

{
  "mcpServers": {
    "things3-gtd": {
      "command": "uv",
      "args": ["run", "server"]
    }
  }
}

Claude Desktop / Claude Mobile / ChatGPT (remote HTTPS)

Front the server with an HTTPS tunnel (ngrok, Cloudflare Tunnel, etc.) and point your client at https://<your-tunnel>/mcp. Full walkthrough: docs/agent-access.md.

n8n / OpenClaw / Cursor

See the dedicated guides:

• n8n
• ChatGPT
• OpenClaw (Clawdbot)
• Publishing / approval notes

Compatibility deep-dives: n8n + FastMCP, ChatGPT + FastMCP.

Tools

19 GTD-native tools organized by stage:

Capture

Clarify

Organize

Reflect

Engage

Utility

GTD context tags

For best results, use consistent GTD tags in Things 3:

Contexts:  @computer, @phone, @office, @home, @errands, @anywhere
Energy:    high-energy, low-energy
Time:      5min, 15min, 30min, 1hr+
Status:    waiting-for
People:    @person-name (for agenda items)

Optional: 24/7 remote access

If you want the server reachable from Claude Mobile, ChatGPT, or any agent off your Mac, run it as a macOS LaunchAgent fronted by an HTTPS tunnel. End-to-end walkthrough: docs/agent-access.md. Recovery procedures for the most common operational issue (a hung Apple Event subsystem): docs/runbook-recovery.md.

Development

For setup, architecture, testing, and contributing guidelines, see docs/DEVELOPERS.md.

# CI-safe tests (no Things 3 required)
uv run python -m pytest tests

# Lint and format
uv run ruff check .
uv run ruff format .

This project uses OpenSpec for spec-driven development of significant changes.

Future direction

This is an evolving experiment in GTD-native AI tooling. Potential directions:

• MCP Resources for ambient GTD state (inbox count, stalled projects)
• Smarter context detection based on time, location, and calendar
• Proactive GTD coaching during weekly reviews
• Multi-app GTD — extending the pattern beyond Things 3

Contributions and ideas welcome.

Credits

• Jonathan Lowin — FastMCP
• things.py — Things 3 Python library
• David Allen — GTD methodology
• Cultured Code — Things 3

License

MIT — see LICENSE.

Links

• GitHub Issues
• Changelog
• Things URL Scheme reference
• GTD methodology