{"id":49418351,"url":"https://github.com/groupthink-dev/things3-blade-mcp","last_synced_at":"2026-04-29T04:12:28.979Z","repository":{"id":347364528,"uuid":"1191669139","full_name":"Groupthink-dev/things3-blade-mcp","owner":"Groupthink-dev","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-28T01:27:03.000Z","size":216,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-29T02:13:00.302Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Groupthink-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-25T13:24:33.000Z","updated_at":"2026-04-28T01:27:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Groupthink-dev/things3-blade-mcp","commit_stats":null,"previous_names":["groupthink-dev/things-3-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Groupthink-dev/things3-blade-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fthings3-blade-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fthings3-blade-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fthings3-blade-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fthings3-blade-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Groupthink-dev","download_url":"https://codeload.github.com/Groupthink-dev/things3-blade-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fthings3-blade-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32410080,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T03:46:11.172Z","status":"ssl_error","status_checked_at":"2026-04-29T03:37:55.317Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-29T04:12:22.560Z","updated_at":"2026-04-29T04:12:28.963Z","avatar_url":"https://github.com/Groupthink-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Things 3 MCP Server\n\nBest-in-class [MCP](https://modelcontextprotocol.io) server for [Things 3](https://culturedcode.com/things/) — token-efficient, full CRUD, AppleScript + URL scheme.\n\nBuilt to be the most capable and efficient Things integration for Claude Desktop, Claude Code, and any MCP-compatible client.\n\n## Features\n\n- **Token-efficient output** — concise one-line-per-item by default, detailed on demand\n- **30+ tools** — full coverage of every Things 3 view and operation\n- **Smart Someday filtering** — correctly handles inherited Someday status (matches Things UI exactly)\n- **Random sampling** — `get_random_inbox(5)` for manageable LLM context instead of dumping hundreds of items\n- **Summary mode** — full GTD overview (`get_summary`) in ~20 lines\n- **AppleScript + URL scheme** — reliable writes with UUID feedback; automatic fallback\n- **Bulk JSON import/export** — Things URL scheme JSON format\n- **HTTP transport** — optional remote access with API key authentication\n- **SKILL.md** — self-teaching instructions so Claude uses tools optimally\n\n## Requirements\n\n- **macOS** (Things 3 is macOS/iOS only)\n- **Things 3** installed and running\n- **Python 3.12+**\n- **uv** (recommended) or pip\n\n## Quick Start\n\n### Install and run\n\n```bash\n# Clone and install\ngit clone https://github.com/Groupthink-dev/things3-blade-mcp.git\ncd things3-blade-mcp\nuv sync\n\n# Run (stdio transport — for Claude Desktop)\nuv run things3-blade-mcp\n```\n\n### Claude Desktop configuration\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"things3\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/things3-blade-mcp\", \"things3-blade-mcp\"]\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\n# Add as MCP server\nclaude mcp add things3 -- uv run --directory /path/to/things3-blade-mcp things3-blade-mcp\n```\n\n## Token-Saving Tips\n\nThe server is designed to minimize LLM context consumption:\n\n1. **Start with `get_summary()`** — 20-line GTD overview, not hundreds of tasks\n2. **Use random sampling** — `get_random_inbox(5)` before `get_inbox(limit=100)`\n3. **Defaults are efficient** — `concise=True`, `limit=10` on all tools\n4. **One-line format**: `□ Buy groceries [3F8A2B1C] | today | deadline:2026-03-01 | #errands`\n5. **Null fields omitted** — no \"Notes: None\" or \"Tags: []\" clutter\n6. **Batch lookups** — no N+1 queries; project/area names resolved in bulk\n\n## All Tools (30)\n\n### List Views (9)\n| Tool | Description |\n|---|---|\n| `get_inbox` | Unprocessed tasks |\n| `get_today` | Today's schedule (Someday-filtered) |\n| `get_upcoming` | Future scheduled tasks |\n| `get_anytime` | Available tasks |\n| `get_someday` | Deferred tasks (includes inherited) |\n| `get_logbook` | Completed tasks (configurable period) |\n| `get_trash` | Trashed tasks |\n| `get_deadlines` | All tasks with deadlines, sorted |\n| `get_summary` | Full GTD overview in ~20 lines |\n\n### Random Sampling (4) — recommended entry points\n| Tool | Description |\n|---|---|\n| `get_random_inbox` | Random sample from inbox |\n| `get_random_today` | Random sample from today |\n| `get_random_anytime` | Random sample from anytime |\n| `get_random_todos` | Random sample, optional project filter |\n\n### Entity Views (5)\n| Tool | Description |\n|---|---|\n| `get_todos` | All open todos (optional project filter) |\n| `get_projects` | Projects with open/done counts |\n| `get_areas` | High-level categories |\n| `get_tags` | All tags |\n| `get_tagged_items` | Todos with a specific tag |\n\n### Search \u0026 Detail (4)\n| Tool | Description |\n|---|---|\n| `search_todos` | Search by title/notes |\n| `search_advanced` | Multi-filter search (status, date, tag, area) |\n| `get_recent` | Recently created items |\n| `show_item` | Single item by UUID with full details |\n\n### Write (4) — AppleScript primary, URL scheme fallback\n| Tool | Description |\n|---|---|\n| `add_todo` | Create a todo (returns UUID) |\n| `add_project` | Create a project with optional todos |\n| `update_todo` | Update any todo field |\n| `update_project` | Update any project field |\n\n### Bulk \u0026 Navigation (4)\n| Tool | Description |\n|---|---|\n| `json_import` | Bulk create via Things JSON format |\n| `json_export` | Export todos as compact JSON |\n| `show_in_things` | Reveal item in Things app |\n| `search_in_things` | Open Things search UI |\n\n## HTTP Transport\n\nFor remote access (e.g., from a different machine or mobile):\n\n```bash\n# Set environment variables\nexport THINGS_MCP_TRANSPORT=http\nexport THINGS_MCP_HOST=127.0.0.1\nexport THINGS_MCP_PORT=8765\nexport THINGS_MCP_API_KEY=your-secret-key-here  # auto-generated if empty\n\n# Run\nuv run things3-blade-mcp\n```\n\n### Bearer Token Authentication\n\nWhen exposing the server through a tunnel or reverse proxy, set `THINGS_MCP_API_TOKEN` to require a bearer token on every request:\n\n```bash\nexport THINGS_MCP_API_TOKEN=your-secret-token-here\n```\n\nAll HTTP requests must then include the header:\n\n```\nAuthorization: Bearer your-secret-token-here\n```\n\nRequests without a valid token receive `401 Unauthorized`. If the env var is **unset or empty**, bearer auth is disabled and the server behaves as before (suitable for localhost-only access).\n\n### Security Warning\n\n**Never expose the HTTP port directly to the internet.** Use a reverse proxy with TLS:\n\n- [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) (recommended — free, zero-config TLS)\n- Caddy (automatic HTTPS)\n- Nginx with Let's Encrypt\n\n#### Cloudflare Tunnel example\n\n```bash\n# Install cloudflared\nbrew install cloudflare/cloudflare/cloudflared\n\n# Create tunnel\ncloudflared tunnel create things-mcp\ncloudflared tunnel route dns things-mcp things-mcp.yourdomain.com\n\n# Run tunnel\ncloudflared tunnel --url http://localhost:8765 run things-mcp\n```\n\n### Testing the HTTP endpoint\n\n```bash\n# Health check\ncurl http://localhost:8765/\n\n# Call a tool (via MCP protocol)\ncurl -X POST http://localhost:8765/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: your-secret-key-here\" \\\n  -d '{\"method\": \"tools/call\", \"params\": {\"name\": \"get_summary\", \"arguments\": {}}}'\n```\n\n## Environment Variables\n\n| Variable | Default | Description |\n|---|---|---|\n| `THINGS_MCP_TRANSPORT` | `stdio` | `stdio` or `http` |\n| `THINGS_MCP_HOST` | `127.0.0.1` | HTTP bind address |\n| `THINGS_MCP_PORT` | `8765` | HTTP port |\n| `THINGS_MCP_API_TOKEN` | (none) | Bearer token for HTTP auth — if set, requires `Authorization: Bearer \u003ctoken\u003e` |\n| `THINGS_MCP_API_KEY` | (auto) | API key for HTTP auth (X-API-Key header) |\n| `THINGS_AUTH_TOKEN` | (auto) | Things URL scheme auth token |\n\n## Architecture\n\n```\nsrc/things3_blade_mcp/\n├── server.py       # FastMCP instance + all 30 @mcp.tool definitions\n├── formatters.py   # Two-tier output: concise (1-line) + detailed\n├── someday.py      # Someday filtering (matches Things UI behavior)\n├── applescript.py   # AppleScript bridge for writes (temp-file approach)\n├── url_scheme.py   # URL scheme builder (fallback writes + checklist items)\n├── sampling.py     # Random sampling helpers\n├── auth.py         # API key auth for HTTP transport\n└── models.py       # Shared constants\n```\n\n**Design principles:**\n- **Reads** via `things.py` (direct SQLite — fast, no app needed)\n- **Writes** via AppleScript (reliable, returns UUIDs, no auth token needed)\n- **Fallback writes** via URL scheme (for checklist items or when AppleScript fails)\n- **Batch lookups** eliminate N+1 queries in formatters\n- **Someday filtering** handles the Things 3 project-inheritance edge case\n\n## Development\n\n```bash\n# Install with dev/test dependencies\nuv sync --all-extras\n\n# Run tests\nuv run pytest tests/ -v\n\n# Lint\nuv run ruff check src/ tests/\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupthink-dev%2Fthings3-blade-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgroupthink-dev%2Fthings3-blade-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupthink-dev%2Fthings3-blade-mcp/lists"}