Things MCP Server

Instructions

Implementation Reference

• src/tools/export-json.ts:94-233 (handler)

  Core handler function that locates the Things database, applies filters based on parameters, executes SQL queries to fetch areas, tags, tasks, projects, checklist items, and task-tag relationships, formats dates, builds summary statistics, and returns structured JSON data.

  function exportThingsData(params: any): any {
    const dbPath = findThingsDatabase();
    logger.info('Exporting Things database', { path: dbPath, params });
    
    // Build status filters
    let statusFilter = 'status = 0 AND trashed = 0'; // Open items only
    if (params.includeCompleted && params.includeTrash) {
      statusFilter = '1=1'; // All items
    } else if (params.includeCompleted) {
      statusFilter = 'trashed = 0'; // All non-trashed
    } else if (params.includeTrash) {
      statusFilter = 'status = 0'; // Open and trashed
    }
    
    const export_data: any = {
      export_info: {
        exported_at: new Date().toISOString(),
        source: 'Things MCP Server',
        database_path: dbPath,
        filters: {
          include_completed: params.includeCompleted,
          include_trash: params.includeTrash,
          minimal: params.minimal
        }
      }
    };
    
    // Export Areas
    const areasData = executeSqlQuery(dbPath, "SELECT uuid, title, visible, index1 FROM TMArea ORDER BY index1");
    export_data.areas = areasData.map(row => {
      const area: any = {
        id: row[0],
        title: row[1] || null,
        visible: row[2] === '1',
        sort_order: parseInt(row[3]) || 0
      };
      
      if (params.minimal) {
        return { id: area.id, title: area.title };
      }
      return area;
    });
    
    // Export Tags
    const tagsData = executeSqlQuery(dbPath, "SELECT uuid, title, shortcut, index1 FROM TMTag ORDER BY index1");
    export_data.tags = tagsData.map(row => {
      const tag: any = {
        id: row[0],
        title: row[1] || null,
        shortcut: row[2] || null,
        sort_order: parseInt(row[3]) || 0
      };
      
      if (params.minimal) {
        return { id: tag.id, title: tag.title };
      }
      return tag;
    });
    
    // Export Tasks and Projects
    const tasksQuery = params.minimal 
      ? `SELECT uuid, title, type, status, trashed, area, project FROM TMTask WHERE ${statusFilter} ORDER BY creationDate`
      : `SELECT uuid, title, notes, type, status, trashed, creationDate, userModificationDate, startDate, deadline, completionDate, area, project, checklistItemsCount, openChecklistItemsCount, index1 FROM TMTask WHERE ${statusFilter} ORDER BY creationDate`;
    
    const tasksData = executeSqlQuery(dbPath, tasksQuery);
    export_data.tasks = tasksData.map(row => {
      if (params.minimal) {
        return {
          id: row[0],
          title: row[1] || null,
          type: parseInt(row[2]) || 0, // 0=task, 1=project, 2=heading
          status: parseInt(row[3]) || 0, // 0=open, 3=completed, 2=canceled
          trashed: row[4] === '1',
          area_id: row[5] || null,
          project_id: row[6] || null
        };
      }
      
      const task: any = {
        id: row[0],
        title: row[1] || null,
        notes: row[2] || null,
        type: parseInt(row[3]) || 0,
        status: parseInt(row[4]) || 0,
        trashed: row[5] === '1',
        creation_date: formatDate(row[6]),
        modification_date: formatDate(row[7]),
        start_date: formatDate(row[8]),
        deadline: formatDate(row[9]),
        completion_date: formatDate(row[10]),
        area_id: row[11] || null,
        project_id: row[12] || null,
        checklist_items_total: parseInt(row[13]) || 0,
        checklist_items_open: parseInt(row[14]) || 0,
        sort_order: parseInt(row[15]) || 0
      };
      
      return task;
    });
    
    // Export Task-Tag relationships
    const taskTagData = executeSqlQuery(dbPath, "SELECT tasks, tags FROM TMTaskTag");
    export_data.task_tags = taskTagData.map(row => ({
      task_id: row[0],
      tag_id: row[1]
    }));
    
    // Export Checklist Items (if not minimal)
    if (!params.minimal) {
      const checklistQuery = `SELECT uuid, title, status, creationDate, task FROM TMChecklistItem WHERE task IN (SELECT uuid FROM TMTask WHERE ${statusFilter}) ORDER BY creationDate`;
      const checklistData = executeSqlQuery(dbPath, checklistQuery);
      export_data.checklist_items = checklistData.map(row => ({
        id: row[0],
        title: row[1] || null,
        status: parseInt(row[2]) || 0, // 0=open, 3=completed
        creation_date: formatDate(row[3]),
        task_id: row[4]
      }));
    }
    
    // Add summary statistics
    export_data.summary = {
      total_areas: export_data.areas.length,
      total_tags: export_data.tags.length,
      total_items: export_data.tasks.length,
      total_tasks: export_data.tasks.filter((t: any) => t.type === 0).length,
      total_projects: export_data.tasks.filter((t: any) => t.type === 1).length,
      total_headings: export_data.tasks.filter((t: any) => t.type === 2).length,
      open_items: export_data.tasks.filter((t: any) => t.status === 0 && !t.trashed).length,
      completed_items: export_data.tasks.filter((t: any) => t.status === 3).length,
      trashed_items: export_data.tasks.filter((t: any) => t.trashed).length
    };
    
    if (!params.minimal) {
      export_data.summary.total_checklist_items = export_data.checklist_items?.length || 0;
      export_data.summary.total_task_tag_relationships = export_data.task_tags.length;
    }
    
    return export_data;
  }

• src/tools/export-json.ts:8-25 (schema)

  Zod schema defining the input parameters for the export_json tool: includeCompleted, includeTrash, minimal, prettify.

  const exportJsonSchema = z.object({
    includeCompleted: z.boolean()
      .optional()
      .default(false)
      .describe('Include completed/canceled tasks and projects in the export (default: false)'),
    includeTrash: z.boolean()
      .optional()
      .default(false)
      .describe('Include trashed items in the export (default: false). Use with caution as this includes deleted data'),
    minimal: z.boolean()
      .optional()
      .default(false)
      .describe('Export minimal data structure with only essential fields (default: false). Reduces output size for processing'),
    prettify: z.boolean()
      .optional()
      .default(true)
      .describe('Pretty-print JSON with indentation (default: true). Set to false for compact single-line output')
  });

• src/tools/export-json.ts:235-273 (registration)

  Registers the 'export_json' tool on the MCP server, providing the name, description, schema, and inline handler that validates platform, calls exportThingsData, stringifies the output, and returns it as text content.

  export function registerExportJsonTool(server: McpServer): void {
    server.tool(
      'export_json',
      'Export complete Things database as structured JSON for debugging, backup, or data processing.',
      exportJsonSchema.shape,
      async (params) => {
        try {
          // Validate macOS platform
          if (process.platform !== 'darwin') {
            throw new Error('Things database access is only available on macOS');
          }
  
          logger.info('Exporting Things database to JSON', { 
            includeCompleted: params.includeCompleted,
            includeTrash: params.includeTrash,
            minimal: params.minimal,
            prettify: params.prettify
          });
          
          const data = exportThingsData(params);
          const jsonOutput = params.prettify ? 
            JSON.stringify(data, null, 2) : 
            JSON.stringify(data);
          
          return {
            content: [{
              type: "text",
              text: jsonOutput
            }]
          };
        } catch (error) {
          logger.error('Failed to export Things database', { 
            error: error instanceof Error ? error.message : error 
          });
          throw error;
        }
      }
    );
  }

• src/index.ts:13-26 (registration)

  Imports and calls registerExportJsonTool during server initialization to register the export_json tool.

  import { registerExportJsonTool } from './tools/export-json.js';
  
  const server = new McpServer({
    name: 'things-mcp',
    version: '1.0.0'
  });
  
  // Register all tools
  registerAddTodoTool(server);
  registerAddProjectTool(server);
  registerUpdateTodoTool(server);
  registerUpdateProjectTool(server);
  registerThingsSummaryTool(server);
  registerExportJsonTool(server);

• src/tools/export-json.ts:27-59 (helper)

  Helper function to locate the Things.app SQLite database file on macOS by searching standard Library/Group Containers paths.

  function findThingsDatabase(): string {
    const homeDir = process.env.HOME || '/Users/' + process.env.USER;
    const thingsGroupContainer = join(homeDir, 'Library/Group Containers');
    
    if (!existsSync(thingsGroupContainer)) {
      throw new Error('Things group container not found. Please ensure Things.app is installed on macOS.');
    }
    
    const containers = readdirSync(thingsGroupContainer);
    const thingsContainer = containers.find(dir => 
      dir.includes('JLMPQHK86H.com.culturedcode.ThingsMac')
    );
    
    if (!thingsContainer) {
      throw new Error('Things container not found. Please ensure Things.app is installed and has been launched at least once.');
    }
    
    const containerPath = join(thingsGroupContainer, thingsContainer);
    const contents = readdirSync(containerPath);
    const thingsDataDir = contents.find(dir => dir.startsWith('ThingsData-'));
    
    if (!thingsDataDir) {
      throw new Error('ThingsData directory not found.');
    }
    
    const dbPath = join(containerPath, thingsDataDir, 'Things Database.thingsdatabase', 'main.sqlite');
    
    if (!existsSync(dbPath)) {
      throw new Error('Things database file not found.');
    }
    
    return dbPath;
  }