### Install Things MCP Server

Source: https://context7.com/hald/things-mcp/llms.txt

Instructions for installing the Things MCP Server using uvx or pip. uvx is the recommended method for direct execution, while pip allows for global installation.

```bash
# Run directly with uvx (recommended)
uvx things-mcp

# Or install globally
pip install things-mcp
```

--------------------------------

### Development Setup Commands

Source: https://github.com/hald/things-mcp/blob/master/CLAUDE.md

Commands to initialize the development environment and execute the MCP server using the uv package manager. Supports both standard stdio and HTTP transport modes.

```bash
# Install dependencies (uses uv package manager)
uv sync

# Run the MCP server (stdio transport, default)
uv run things-mcp

# Run with HTTP transport
THINGS_MCP_TRANSPORT=http uv run things-mcp
```

--------------------------------

### Install Things MCP Server via Claude Code

Source: https://github.com/hald/things-mcp/blob/master/README.md

Command-line instructions to add the Things MCP server to Claude Code, with an optional flag for global availability.

```bash
claude mcp add-json things '{"command":"uvx","args":["things-mcp"]}'

# Global installation
claude mcp add-json -s user things '{"command":"uvx","args":["things-mcp"]}'
```

--------------------------------

### Run Test Suite with Pytest

Source: https://github.com/hald/things-mcp/blob/master/README.md

Commands to install test dependencies and execute the unit test suite using the uv package manager. Supports running all tests, verbose output, or specific test subsets.

```bash
# Install test dependencies
uv sync --extra test

# Run all tests
uv run pytest

# Run tests with verbose output
uv run pytest -v

# Run a specific test file
uv run pytest tests/test_url_scheme.py

# Run tests matching a pattern
uv run pytest -k "test_add_todo"
```

--------------------------------

### Test Suite Execution Commands

Source: https://github.com/hald/things-mcp/blob/master/CLAUDE.md

Commands for managing and running the project's unit test suite using pytest. Includes options for installing test dependencies, verbose output, and filtering tests by file or pattern.

```bash
# Install test dependencies
uv sync --extra test

# Run all tests
uv run pytest

# Run tests with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_url_scheme.py

# Run tests matching a pattern
uv run pytest -k "test_format"
```

--------------------------------

### Get Upcoming Todos with Things MCP Server

Source: https://context7.com/hald/things-mcp/llms.txt

Python code snippet to retrieve todos scheduled for future dates using the Things MCP Server. It excludes tasks from Someday projects and includes todos with future start dates and reminders.

```python
# MCP tool call
result = await get_upcoming()

# Returns formatted upcoming todos with start dates
# Includes todos with future start dates and reminders
```

--------------------------------

### Get Anytime Todos with Things MCP Server

Source: https://context7.com/hald/things-mcp/llms.txt

Python code snippet to retrieve todos from the Anytime list using the Things MCP Server. Tasks belonging to Someday projects are excluded.

```python
# MCP tool call
result = await get_anytime()

# Returns Anytime todos excluding Someday project tasks
```

--------------------------------

### Get Projects with Optional Task Inclusion (Things MCP Server)

Source: https://context7.com/hald/things-mcp/llms.txt

Python code snippet to retrieve projects from Things using the MCP Server. It allows for fetching only project metadata or including the contained tasks.

```python
# Get all projects (metadata only)
result = await get_projects()

# Get projects with their tasks included
result = await get_projects(include_items=True)
```

--------------------------------

### Get Recent Items

Source: https://github.com/hald/things-mcp/blob/master/README.md

Retrieves a list of recently created or modified items within a specified time period.

```APIDOC
## GET /hald/things-mcp/get-recent

### Description
Retrieves a list of recent items.

### Method
GET

### Endpoint
/hald/things-mcp/get-recent

### Parameters
#### Query Parameters
- **period** (string) - Required - Time period for recent items (e.g., '3d', '1w', '2m', '1y')

### Response
#### Success Response (200)
- **items** (array) - A list of recent items.

#### Response Example
```json
{
  "items": [
    {
      "id": "uuid-item-2",
      "title": "Recent Task",
      "creationDate": "2024-01-10T10:00:00Z"
    }
  ]
}
```
```

--------------------------------

### Get Logbook Entries with Things MCP Server

Source: https://context7.com/hald/things-mcp/llms.txt

Python code snippet to retrieve completed todos from the Logbook using the Things MCP Server. Supports configurable time periods and result limits.

```python
# Get completed todos from last 7 days (default)
result = await get_logbook()

# Get completed todos from last 30 days, max 100 items
result = await get_logbook(period="30d", limit=100)

# Get completed todos from last week
result = await get_logbook(period="1w", limit=25)

# Period formats: '3d' (days), '1w' (weeks), '2m' (months), '1y' (years)
```

--------------------------------

### Get Todos with Filtering by Project (Things MCP Server)

Source: https://context7.com/hald/things-mcp/llms.txt

Python code snippet demonstrating how to retrieve todos using the Things MCP Server, with options to filter by project UUID and exclude checklist items for faster responses. Includes error handling for invalid project UUIDs.

```python
# Get all todos
result = await get_todos()

# Get todos from a specific project by UUID
result = await get_todos(project_uuid="ABC123-DEF456-GHI789")

# Exclude checklist items for faster response
result = await get_todos(project_uuid="ABC123", include_items=False)

# Error handling for invalid project UUID:
# Returns: "Error: Invalid project UUID 'invalid-uuid'"
```

--------------------------------

### Get Someday Todos with Things MCP Server

Source: https://context7.com/hald/things-mcp/llms.txt

Python code snippet to retrieve todos from the Someday list using the Things MCP Server. This includes tasks that inherit the Someday status from their parent project.

```python
# MCP tool call
result = await get_someday()

# Example response includes inherited status:
"""
Title: Research vacation destinations
UUID: MNO345-PQR678
Type: to-do
List: Someday (inherited from project)
Project: Summer Vacation Planning
"""
```

--------------------------------

### Get Trash Items with Things MCP Server

Source: https://context7.com/hald/things-mcp/llms.txt

Python code snippet to retrieve all trashed todos that have not been permanently deleted using the Things MCP Server. Returns formatted trashed todos with full metadata.

```python
# MCP tool call
result = await get_trash()

# Returns formatted trashed todos with full metadata
```

--------------------------------

### Get Inbox Todos with Things MCP Server

Source: https://context7.com/hald/things-mcp/llms.txt

Python code snippet to retrieve all todos from the Things 3 Inbox using the Things MCP Server. The response includes full metadata for each todo item.

```python
# MCP tool call
result = await get_inbox()

# Example response:
"""
Title: Review quarterly report
UUID: ABC123-DEF456
Type: to-do
Status: incomplete
List: Inbox
Created: 2024-01-15 10:30:00
Age: 3 days ago
Notes: Need to check sales figures
Tags: work, urgent

---

Title: Buy groceries
UUID: GHI789-JKL012
Type: to-do
Status: incomplete
List: Inbox
Created: 2024-01-17 14:00:00
Age: 1 day ago
Checklist:
  ☐ Milk
  ☐ Bread
  ✓ Eggs
"""
```

--------------------------------

### Update Todo Item Attributes

Source: https://context7.com/hald/things-mcp/llms.txt

Provides examples for modifying existing todo items using their unique ID. This includes updating the title, notes, rescheduling the 'when' date/time, setting or updating a deadline, replacing tags, marking as completed or canceled, and moving the todo to a different project or heading.

```python
# Update todo title
result = await update_todo(
    id="TODO-123-456",
    title="Updated: Review quarterly report"
)

# Update todo notes
result = await update_todo(
    id="TODO-123-456",
    notes="Updated notes with new information"
)

# Reschedule a todo
result = await update_todo(
    id="TODO-123-456",
    when="tomorrow"
)

# Add a reminder to existing todo
result = await update_todo(
    id="TODO-123-456",
    when="2024-01-20@15:00"
)

# Update deadline
result = await update_todo(
    id="TODO-123-456",
    deadline="2024-02-15"
)

# Update tags (replaces existing tags)
result = await update_todo(
    id="TODO-123-456",
    tags=["urgent", "priority"]
)

# Mark todo as completed
result = await update_todo(
    id="TODO-123-456",
    completed=True
)

# Mark todo as canceled
result = await update_todo(
    id="TODO-123-456",
    canceled=True
)

# Move todo to a different project (by title)
result = await update_todo(
    id="TODO-123-456",
    list="New Project Name"
)

# Move todo to a different project (by UUID)
result = await update_todo(
    id="TODO-123-456",
    list_id="PRJ-789-012"
)

# Move todo under a different heading (by title)
result = await update_todo(
    id="TODO-123-456",
    heading="Development Phase"
)

# Move todo under a different heading (by UUID)
result = await update_todo(
    id="TODO-123-456",
    heading_id="HDG-555-666"
)

# Move todo to Someday
result = await update_todo(
    id="TODO-123-456",
    when="someday"
)
```

--------------------------------

### Configure HTTP Transport for Things MCP

Source: https://context7.com/hald/things-mcp/llms.txt

Configures the Things MCP server for remote access using HTTP transport. This involves setting environment variables for transport type, host, and port. The examples show how to run the server with HTTP enabled.

```bash
# Environment variables for HTTP transport
THINGS_MCP_TRANSPORT=http    # "stdio" (default) or "http"
THINGS_MCP_HOST=127.0.0.1    # HTTP server bind address
THINGS_MCP_PORT=8000         # HTTP server port

# Run with HTTP transport using uvx
THINGS_MCP_TRANSPORT=http THINGS_MCP_HOST=0.0.0.0 THINGS_MCP_PORT=8000 uvx things-mcp

# Run from source with HTTP transport
THINGS_MCP_TRANSPORT=http THINGS_MCP_HOST=0.0.0.0 THINGS_MCP_PORT=8000 uv run things-mcp
```

--------------------------------

### Get Today's Todos with Things MCP Server

Source: https://context7.com/hald/things-mcp/llms.txt

Python code snippet to retrieve todos scheduled for today using the Things MCP Server. This function automatically filters out tasks from Someday projects to align with the Things UI.

```python
# MCP tool call
result = await get_today()

# Returns formatted todos due today with full metadata
# Tasks from Someday projects are excluded from results
```

--------------------------------

### Add Todo with Tags, Reminders, and Project Assignment

Source: https://context7.com/hald/things-mcp/llms.txt

Demonstrates creating a new todo item with various attributes. This includes setting a title, tags, a specific reminder time, and assigning it to a project either by its title or UUID. It also shows how to add todos under specific headings within a project.

```python
result = await add_todo(
    title="Fix production bug",
    tags=["urgent", "work"],
    when="today"
)

result = await add_todo(
    title="Call dentist",
    when="2024-01-15@14:30"  # Reminder at 2:30 PM
)

result = await add_todo(
    title="Create wireframes",
    list_title="Website Redesign"
)

result = await add_todo(
    title="Review competitor sites",
    list_id="PRJ-123-456"
)

result = await add_todo(
    title="Set up staging server",
    list_title="Website Redesign",
    heading="Development Phase"
)

result = await add_todo(
    title="Deploy to production",
    heading_id="HDG-333-444"
)

result = await add_todo(
    title="Prepare presentation",
    notes="Q1 sales review for executive team",
    when="2024-01-25@09:00",
    deadline="2024-01-26",
    tags=["work", "important"],
    checklist_items=[
        "Gather sales data",
        "Create slides",
        "Review with manager",
        "Practice delivery"
    ],
    list_title="Q1 Marketing Campaign",
    heading="Deliverables"
)
```

--------------------------------

### Add Project with Initial Todos, Area, and Scheduling

Source: https://context7.com/hald/things-mcp/llms.txt

Illustrates the creation of new projects within Things. This function allows for setting a project title, adding initial todo items, specifying notes, assigning the project to an area (by title or UUID), and setting scheduling parameters like 'when' and 'deadline'. It also supports creating 'someday' projects.

```python
# Create a simple project
result = await add_project(title="Website Redesign")

# Create a project with notes
result = await add_project(
    title="Q1 Marketing Campaign",
    notes="Focus on social media and email marketing"
)

# Create a project with initial todos
result = await add_project(
    title="Home Renovation",
    todos=[
        "Get contractor quotes",
        "Review permits required",
        "Set budget",
        "Create timeline"
    ]
)

# Create a project in a specific area (by title)
result = await add_project(
    title="New Product Launch",
    area_title="Work"
)

# Create a project in a specific area (by UUID)
result = await add_project(
    title="Side Project",
    area_id="AREA-789-012"
)

# Create a project with deadline and tags
result = await add_project(
    title="Tax Preparation",
    notes="Gather all documents for accountant",
    when="2024-03-01",
    deadline="2024-04-15",
    tags=["financial", "annual"]
)

# Create a project with a reminder
result = await add_project(
    title="Quarterly Review",
    when="2024-03-31@10:00"  # Reminder at 10 AM
)

# Create a Someday project
result = await add_project(
    title="Learn Spanish",
    notes="Research apps and courses",
    when="someday"
)

# Full-featured project creation
result = await add_project(
    title="Summer Vacation Planning",
    notes="Family trip to Europe",
    when="someday",
    deadline="2024-06-01",
    tags=["personal", "travel"],
    area_title="Personal",
    todos=[
        "Research destinations",
        "Check passport expiration",
        "Set vacation budget",
        "Book flights",
        "Reserve accommodations"
    ]
)
```

--------------------------------

### Basic Operations

Source: https://context7.com/hald/things-mcp/llms.txt

Endpoints for general todo and project retrieval with filtering options.

```APIDOC
## GET /todos

### Description
Retrieves todos with optional filtering by project. Returns all todos when no project is specified.

### Method
GET

### Endpoint
/todos

### Parameters
#### Query Parameters
- **project_uuid** (string) - Optional - The UUID of the project to filter todos by.
- **include_items** (boolean) - Optional - Whether to include checklist items in the response. Defaults to true.

### Request Example
```python
# Get all todos
result = await get_todos()

# Get todos from a specific project by UUID
result = await get_todos(project_uuid="ABC123-DEF456-GHI789")

# Exclude checklist items for faster response
result = await get_todos(project_uuid="ABC123", include_items=False)
```

### Response
#### Success Response (200)
- **todos** (array) - A list of todo objects, optionally filtered by project and including/excluding checklist items.

#### Error Response
- **message** (string) - "Error: Invalid project UUID 'invalid-uuid'"

## GET /projects

### Description
Retrieves all projects from Things with optional inclusion of contained tasks.

### Method
GET

### Endpoint
/projects

### Parameters
#### Query Parameters
- **include_items** (boolean) - Optional - Whether to include tasks within each project. Defaults to false.

### Request Example
```python
# Get all projects (metadata only)
result = await get_projects()

# Get projects with their tasks included
result = await get_projects(include_items=True)
```

### Response
#### Success Response (200)
- **projects** (array) - A list of project objects, optionally including their contained tasks.
```

--------------------------------

### Show Item Navigation

Source: https://context7.com/hald/things-mcp/llms.txt

Opens the Things app to display a specific item or list view.

```APIDOC
## POST /hald/things-mcp/show_item

### Description
Opens the Things app to show a specific item or list view. Useful for directing user attention.

### Method
POST

### Endpoint
/hald/things-mcp/show_item

### Parameters
#### Request Body
- **id** (string) - Required - The unique identifier of the item or list (e.g., "TODO-123-456", "inbox", "today").
- **query** (string) - Optional - A search query to apply when showing a list.
- **filter_tags** (array of strings) - Optional - A list of tags to filter the view by.

### Request Example
```json
{
  "id": "today",
  "filter_tags": ["work", "urgent"]
}
```

### Response
#### Success Response (200)
- **result** (any) - The result of the operation.
```

--------------------------------

### Search Items

Source: https://context7.com/hald/things-mcp/llms.txt

Opens the Things app search interface with a specified query.

```APIDOC
## POST /hald/things-mcp/search_items

### Description
Opens the Things app search interface with a specified query.

### Method
POST

### Endpoint
/hald/things-mcp/search_items

### Parameters
#### Request Body
- **query** (string) - Required - The search query string.

### Request Example
```json
{
  "query": "quarterly report"
}
```

### Response
#### Success Response (200)
- **result** (any) - The result of the search operation.
```

--------------------------------

### Configure and Run HTTP Transport

Source: https://github.com/hald/things-mcp/blob/master/README.md

Instructions for running the Things MCP server using HTTP transport instead of the default stdio. Requires setting environment variables for host and port.

```bash
# Using uvx
THINGS_MCP_TRANSPORT=http THINGS_MCP_HOST=0.0.0.0 THINGS_MCP_PORT=8000 uvx things-mcp

# Or from source
THINGS_MCP_TRANSPORT=http THINGS_MCP_HOST=0.0.0.0 THINGS_MCP_PORT=8000 uv run things-mcp
```

--------------------------------

### Search Todo Items

Source: https://context7.com/hald/things-mcp/llms.txt

Provides basic and advanced search capabilities. search_todos performs simple text matching, while search_advanced supports complex filtering by status, dates, tags, and types.

```python
# Simple search
result = await search_todos(query="meeting")

# Advanced search with multiple filters
result = await search_advanced(
    status="incomplete",
    tag="work",
    last="1w"
)

# Get recently created items
result = await get_recent(period="3d")
```

--------------------------------

### Scheduling with Reminders

Source: https://github.com/hald/things-mcp/blob/master/README.md

Endpoints for adding and updating todos and projects, with support for scheduling tasks using various date and time formats, including reminders.

```APIDOC
## POST /hald/things-mcp/add-todo
## POST /hald/things-mcp/add-project
## PUT /hald/things-mcp/update-todo
## PUT /hald/things-mcp/update-project

### Description
Adds or updates todos and projects. Supports scheduling tasks with flexible date/time formats and reminders.

### Method
POST / PUT

### Endpoint
/hald/things-mcp/add-todo
/hald/things-mcp/add-project
/hald/things-mcp/update-todo
/hald/things-mcp/update-project

### Parameters
#### Query Parameters
- **when** (string) - Optional - Scheduling information. Accepts keywords (`today`, `tomorrow`, `evening`, `anytime`, `someday`), date (`YYYY-MM-DD`), or datetime with reminder (`YYYY-MM-DD@HH:MM`).

### Request Body (for add/update operations)
- **title** (string) - Required - The title of the todo or project.
- **notes** (string) - Optional - Additional notes for the item.
- **area** (string) - Optional - UUID of the area to assign the item to.
- **tags** (array of strings) - Optional - UUIDs of tags to assign to the item.
- **checklist** (array of strings) - Optional - Items for a checklist (for projects).

### Request Example (add-todo)
```json
{
  "title": "Schedule a meeting",
  "notes": "Discuss project roadmap",
  "when": "2024-01-15@14:00",
  "area": "uuid-area-1",
  "tags": ["uuid-tag-1"]
}
```

### Response
#### Success Response (200)
- **id** (string) - The UUID of the created or updated item.

#### Response Example
```json
{
  "id": "uuid-new-item-1"
}
```
```

--------------------------------

### List View Tools

Source: https://context7.com/hald/things-mcp/llms.txt

Tools for retrieving specific lists of todos from Things 3, with automatic filtering and metadata.

```APIDOC
## GET /inbox

### Description
Retrieves all todos currently in the Things Inbox. Returns formatted todo items with full metadata including UUID, status, notes, dates, tags, and checklist items.

### Method
GET

### Endpoint
/inbox

### Parameters
None

### Request Example
```python
# MCP tool call
result = await get_inbox()
```

### Response
#### Success Response (200)
- **todos** (array) - A list of todo objects with full metadata.

#### Response Example
```
Title: Review quarterly report
UUID: ABC123-DEF456
Type: to-do
Status: incomplete
List: Inbox
Created: 2024-01-15 10:30:00
Age: 3 days ago
Notes: Need to check sales figures
Tags: work, urgent

---

Title: Buy groceries
UUID: GHI789-JKL012
Type: to-do
Status: incomplete
List: Inbox
Created: 2024-01-17 14:00:00
Age: 1 day ago
Checklist:
  ☐ Milk
  ☐ Bread
  ✓ Eggs
```

## GET /today

### Description
Retrieves all todos scheduled for today. Automatically filters out tasks belonging to Someday projects to match Things UI behavior.

### Method
GET

### Endpoint
/today

### Parameters
None

### Request Example
```python
# MCP tool call
result = await get_today()
```

### Response
#### Success Response (200)
- **todos** (array) - A list of todo objects due today, excluding tasks from Someday projects.

## GET /upcoming

### Description
Retrieves all todos scheduled for future dates. Tasks from Someday projects are filtered out. Tasks with datetime scheduling (e.g., `2099-01-01@10:00`) appear here.

### Method
GET

### Endpoint
/upcoming

### Parameters
None

### Request Example
```python
# MCP tool call
result = await get_upcoming()
```

### Response
#### Success Response (200)
- **todos** (array) - A list of todo objects with future start dates and reminders, excluding tasks from Someday projects.

## GET /anytime

### Description
Retrieves todos from the Anytime list. Filters out tasks that belong to Someday projects, either directly or through headings.

### Method
GET

### Endpoint
/anytime

### Parameters
None

### Request Example
```python
# MCP tool call
result = await get_anytime()
```

### Response
#### Success Response (200)
- **todos** (array) - A list of Anytime todos excluding tasks from Someday projects.

## GET /someday

### Description
Retrieves todos from the Someday list, including tasks that inherit Someday status from their parent project. Tasks in Someday projects show "(inherited from project)" in the List field.

### Method
GET

### Endpoint
/someday

### Parameters
None

### Request Example
```python
# MCP tool call
result = await get_someday()
```

### Response
#### Success Response (200)
- **todos** (array) - A list of Someday todos, including those with inherited status.

#### Response Example
```
Title: Research vacation destinations
UUID: MNO345-PQR678
Type: to-do
List: Someday (inherited from project)
Project: Summer Vacation Planning
```

## GET /logbook

### Description
Retrieves completed todos from the Logbook with configurable time period and result limit.

### Method
GET

### Endpoint
/logbook

### Parameters
#### Query Parameters
- **period** (string) - Optional - The time period for completed todos. Formats: '3d' (days), '1w' (weeks), '2m' (months), '1y' (years). Defaults to '7d'.
- **limit** (integer) - Optional - The maximum number of items to return. Defaults to no limit.

### Request Example
```python
# Get completed todos from last 7 days (default)
result = await get_logbook()

# Get completed todos from last 30 days, max 100 items
result = await get_logbook(period="30d", limit=100)

# Get completed todos from last week
result = await get_logbook(period="1w", limit=25)
```

### Response
#### Success Response (200)
- **todos** (array) - A list of completed todo objects within the specified period and limit.

## GET /trash

### Description
Retrieves all trashed todos that haven't been permanently deleted.

### Method
GET

### Endpoint
/trash

### Parameters
None

### Request Example
```python
# MCP tool call
result = await get_trash()
```

### Response
#### Success Response (200)
- **todos** (array) - A list of trashed todo objects with full metadata.

```

--------------------------------

### Configure Things MCP Server in Claude Desktop

Source: https://github.com/hald/things-mcp/blob/master/README.md

JSON configuration snippet to register the Things MCP server within the Claude Desktop configuration file.

```json
{
  "mcpServers": {
    "things": {
      "command": "uvx",
      "args": ["things-mcp"]
    }
  }
}
```

--------------------------------

### Create Todo Items

Source: https://context7.com/hald/things-mcp/llms.txt

Functionality to create new todos in Things. Supports scheduling, deadlines, notes, and checklist item assignment.

```python
# Create a todo with a checklist
result = await add_todo(
    title="Pack for vacation",
    notes="Beach trip next week",
    when="2024-01-20",
    checklist_items=["Sunscreen", "Swimsuit", "Beach towel", "Sunglasses"]
)
```

--------------------------------

### Search Items in Things App

Source: https://context7.com/hald/things-mcp/llms.txt

Opens the Things app's search interface with a provided query. This function allows users to quickly find items within the Things application based on specific keywords or patterns.

```python
# Search in Things UI
result = await search_items(query="quarterly report")

# Search for test items
result = await search_items(query="[MCP-TEST]")

# Search with special characters
result = await search_items(query="meeting & review")
```

--------------------------------

### Show Item in Things App

Source: https://context7.com/hald/things-mcp/llms.txt

Opens the Things app to display a specific item or list view using its ID. This is useful for directing user attention. It supports showing todos, projects, and predefined views like Inbox, Today, and Upcoming.

```python
# Show a specific todo or project by UUID
result = await show_item(id="TODO-123-456")

# Show the Inbox
result = await show_item(id="inbox")

# Show Today view
result = await show_item(id="today")

# Show Upcoming view
result = await show_item(id="upcoming")

# Show Anytime view
result = await show_item(id="anytime")

# Show Someday view
result = await show_item(id="someday")

# Show Logbook
result = await show_item(id="logbook")

# Show a list with a search query
result = await show_item(
    id="today",
    query="meeting"
)

# Show a list filtered by tags
result = await show_item(
    id="anytime",
    filter_tags=["work", "urgent"]
)
```

--------------------------------

### Retrieve Areas and Headings

Source: https://context7.com/hald/things-mcp/llms.txt

Functions to fetch organizational structures within Things. get_areas retrieves areas with optional nested items, while get_headings filters project-specific headings.

```python
# Get all areas (metadata only)
result = await get_areas()

# Get areas with contained items
result = await get_areas(include_items=True)

# Get all headings across all projects
result = await get_headings()

# Get headings for a specific project
result = await get_headings(project_uuid="PRJ-123-456")
```

--------------------------------

### Project, Area, and Tag Retrieval

Source: https://github.com/hald/things-mcp/blob/master/README.md

Endpoints to retrieve projects, areas, and tags. The `get-projects` endpoint supports an optional `include_items` parameter to include contained items.

```APIDOC
## GET /hald/things-mcp/get-projects

### Description
Retrieves a list of projects. Optionally includes contained items.

### Method
GET

### Endpoint
/hald/things-mcp/get-projects

### Parameters
#### Query Parameters
- **include_items** (boolean) - Optional - Include contained items (default: false)

### Response
#### Success Response (200)
- **projects** (array) - A list of project objects.
- **areas** (array) - A list of area objects.
- **tags** (array) - A list of tag objects.

#### Response Example
```json
{
  "projects": [
    {
      "id": "uuid-project-1",
      "title": "Project Alpha",
      "items": []
    }
  ],
  "areas": [
    {
      "id": "uuid-area-1",
      "title": "Work"
    }
  ],
  "tags": [
    {
      "id": "uuid-tag-1",
      "title": "Urgent"
    }
  ]
}
```
```

--------------------------------

### Things MCP Server API

Source: https://github.com/hald/things-mcp/blob/master/README.md

This section details the various tools and operations available through the Things MCP Server.

```APIDOC
## Things MCP Server API Documentation

This API provides access to your Things 3 data through the Model Context Protocol (MCP).

### Available Tools

#### List Views

- `get-inbox`: Retrieves todos from the Inbox.
- `get-today`: Retrieves todos due today.
- `get-upcoming`: Retrieves upcoming todos.
- `get-anytime`: Retrieves todos from the Anytime list.
- `get-someday`: Retrieves todos from the Someday list, including tasks in Someday projects.
- `get-logbook`: Retrieves completed todos.
- `get-trash`: Retrieves trashed todos.

#### Basic Operations

- `get-todos`: Retrieves todos, optionally filtered by project.
  - **Parameters**:
    - `project_uuid` (optional): Filter todos by project.
    - `include_items` (optional, default: true): Include checklist items.
- `get-projects`: Retrieves all projects.
- `get-areas`: Retrieves all areas.

#### Tag Operations

- `get-tags`: Retrieves all tags.
- `get-tagged-items`: Retrieves items with a specific tag.

#### Search Operations

- `search-todos`: Performs a simple search by title/notes.
- `search-advanced`: Performs an advanced search with multiple filters.

#### Time-based Operations

- `get-recent`: Retrieves recently created items.

#### Things URL Scheme Operations

- `add-todo`: Creates a new todo.
- `add-project`: Creates a new project.
- `update-todo`: Updates an existing todo.
- `update-project`: Updates an existing project.
- `show-item`: Shows a specific item or list in Things.
- `search-items`: Searches for items in Things.
```

--------------------------------

### Configure Claude Code for Things MCP Server

Source: https://context7.com/hald/things-mcp/llms.txt

Bash commands to configure Claude Code to use the Things MCP Server. This includes options for adding the configuration to the current project or globally.

```bash
# Add to current project
claude mcp add-json things '{"command":"uvx","args":["things-mcp"]}'

# Add globally (across all projects)
claude mcp add-json -s user things '{"command":"uvx","args":["things-mcp"]}'
```

--------------------------------

### Update Todo Item

Source: https://context7.com/hald/things-mcp/llms.txt

Allows for a full update of a todo item with multiple fields.

```APIDOC
## POST /hald/things-mcp/update_todo

### Description
Updates an existing todo item with specified fields.

### Method
POST

### Endpoint
/hald/things-mcp/update_todo

### Parameters
#### Request Body
- **id** (string) - Required - The unique identifier of the todo item.
- **title** (string) - Optional - The updated title for the todo item.
- **notes** (string) - Optional - The updated notes for the todo item.
- **when** (string) - Optional - The date and time for the todo item (e.g., "2024-01-25@10:00").
- **deadline** (string) - Optional - The deadline for the todo item (e.g., "2024-01-30").
- **tags** (array of strings) - Optional - A list of tags to associate with the todo item.
- **list_id** (string) - Optional - The ID of the list the todo item belongs to.
- **heading** (string) - Optional - The heading for the todo item.

### Request Example
```json
{
  "id": "TODO-123-456",
  "title": "Updated Task Title",
  "notes": "Comprehensive updated notes",
  "when": "2024-01-25@10:00",
  "deadline": "2024-01-30",
  "tags": ["updated", "important"],
  "list_id": "PRJ-NEW-123",
  "heading": "New Section"
}
```

### Response
#### Success Response (200)
- **result** (any) - The result of the update operation.
```

--------------------------------

### Update Project Item

Source: https://context7.com/hald/things-mcp/llms.txt

Allows for updating various fields of an existing project item.

```APIDOC
## POST /hald/things-mcp/update_project

### Description
Updates an existing project by UUID with various fields.

### Method
POST

### Endpoint
/hald/things-mcp/update_project

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.

#### Request Body
- **title** (string) - Optional - The updated title for the project.
- **notes** (string) - Optional - The updated notes for the project.
- **when** (string) - Optional - The date and time for the project (e.g., "anytime", "2024-04-01@09:00").
- **deadline** (string) - Optional - The deadline for the project (e.g., "2024-06-30").
- **tags** (array of strings) - Optional - A list of tags to associate with the project.
- **completed** (boolean) - Optional - Set to true to mark the project as completed.
- **canceled** (boolean) - Optional - Set to true to mark the project as canceled.

### Request Example
```json
{
  "id": "PRJ-123-456",
  "title": "Q2 Marketing Campaign - Updated",
  "notes": "Revised strategy based on Q1 results",
  "when": "2024-04-01@09:00",
  "deadline": "2024-06-30",
  "tags": ["marketing", "priority", "q2"]
}
```

### Response
#### Success Response (200)
- **result** (any) - The result of the update operation.
```

--------------------------------

### Manage Tags and Tagged Items

Source: https://context7.com/hald/things-mcp/llms.txt

Operations to retrieve tags and items associated with specific tags. These functions allow for filtering and metadata retrieval based on tag assignments.

```python
# Get all tags (metadata only)
result = await get_tags()

# Get tags with their tagged items
result = await get_tags(include_items=True)

# Get all items with the "urgent" tag
result = await get_tagged_items(tag="urgent")
```

--------------------------------

### Update Project Item

Source: https://context7.com/hald/things-mcp/llms.txt

Updates an existing project by its UUID. This function allows modification of various project attributes like title, notes, scheduling, deadline, tags, and completion status. Authentication is handled automatically.

```python
# Update project title
result = await update_project(
    id="PRJ-123-456",
    title="Website Redesign - Phase 2"
)

# Update project notes
result = await update_project(
    id="PRJ-123-456",
    notes="Updated scope to include mobile responsive design"
)

# Reschedule project
result = await update_project(
    id="PRJ-123-456",
    when="anytime"
)

# Update project deadline
result = await update_project(
    id="PRJ-123-456",
    deadline="2024-06-30"
)

# Update project tags
result = await update_project(
    id="PRJ-123-456",
    tags=["priority", "q2"]
)

# Mark project as completed
result = await update_project(
    id="PRJ-123-456",
    completed=True
)

# Mark project as canceled
result = await update_project(
    id="PRJ-123-456",
    canceled=True
)

# Move project to Someday
result = await update_project(
    id="PRJ-123-456",
    when="someday"
)

# Full project update
result = await update_project(
    id="PRJ-123-456",
    title="Q2 Marketing Campaign - Updated",
    notes="Revised strategy based on Q1 results",
    when="2024-04-01@09:00",
    deadline="2024-06-30",
    tags=["marketing", "priority", "q2"]
)
```

--------------------------------

### Update Todo Item

Source: https://context7.com/hald/things-mcp/llms.txt

Updates an existing todo item with various fields. Requires the todo item's ID. Supports updating title, notes, due date, tags, and list assignment.

```python
result = await update_todo(
    id="TODO-123-456",
    title="Updated Task Title",
    notes="Comprehensive updated notes",
    when="2024-01-25@10:00",
    deadline="2024-01-30",
    tags=["updated", "important"],
    list_id="PRJ-NEW-123",
    heading="New Section"
)
```

--------------------------------

### Advanced Search

Source: https://github.com/hald/things-mcp/blob/master/README.md

Perform an advanced search for items based on various criteria such as status, dates, tags, areas, and types.

```APIDOC
## GET /hald/things-mcp/search-advanced

### Description
Performs an advanced search for items based on specified filters.

### Method
GET

### Endpoint
/hald/things-mcp/search-advanced

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by status (incomplete/completed/canceled)
- **start_date** (string) - Optional - Filter by start date (YYYY-MM-DD)
- **deadline** (string) - Optional - Filter by deadline (YYYY-MM-DD)
- **tag** (string) - Optional - Filter by tag UUID
- **area** (string) - Optional - Filter by area UUID
- **type** (string) - Optional - Filter by item type (to-do/project/heading)
- **last** (string) - Optional - Filter by creation date (e.g., '3d' for last 3 days, '1w' for last week)

### Response
#### Success Response (200)
- **items** (array) - A list of items matching the search criteria.

#### Response Example
```json
{
  "items": [
    {
      "id": "uuid-item-1",
      "title": "Task 1",
      "status": "incomplete"
    }
  ]
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.