macOS Calendar MCP Server

Instructions

Implementation Reference

• macos-calendar-mcp-sdk.js:498-557 (handler)

  Main handler function for 'list-week-events' tool. Parses weekStart, formats dates, executes AppleScript to query Calendar app for events in the week, formats and returns the list.

  async listWeekEvents(args) {
    const { weekStart, calendar = '工作' } = args;
    
    const startDate = new Date(weekStart);
    const endDate = new Date(startDate);
    endDate.setDate(startDate.getDate() + 7);
    
    const formattedStart = this.formatDateForAppleScript(weekStart + ' 00:00');
    const formattedEnd = this.formatDateForAppleScript(endDate.toISOString().split('T')[0] + ' 00:00');
    
    const script = `
      tell application "Calendar"
        set theCalendar to calendar "${calendar}"
        set weekStart to date "${formattedStart}"
        set weekEnd to date "${formattedEnd}"
        
        set weekEvents to every event of theCalendar whose start date ≥ weekStart and start date < weekEnd
        
        set eventList to {}
        repeat with anEvent in weekEvents
          set eventInfo to (summary of anEvent) & "|" & (start date of anEvent) & "|" & (end date of anEvent) & "|" & (location of anEvent)
          set end of eventList to eventInfo
        end repeat
        
        return eventList as string
      end tell
    `;
  
    try {
      const result = execSync(`osascript -e '${script}'`, { encoding: 'utf8' });
      const events = result.trim();
      
      if (!events || events === '""') {
        return {
          content: [
            {
              type: 'text',
              text: `📅 ${calendar} - ${weekStart}这周无事件`,
            },
          ],
        };
      }
  
      const eventList = events.split(',').map(event => {
        const [title, start, end, loc] = event.trim().split('|');
        return `📝 ${title}\n🕒 ${start} - ${end}${loc ? `\n📍 ${loc}` : ''}`;
      }).join('\n\n');
  
      return {
        content: [
          {
            type: 'text',
            text: `📅 ${calendar} - ${weekStart}这周的事件:\n\n${eventList}`,
          },
        ],
      };
    } catch (error) {
      throw new Error(`获取周事件失败: ${error.message}`);
    }
  }

• macos-calendar-mcp-sdk.js:152-169 (schema)

  Input schema definition for the 'list-week-events' tool, defining parameters weekStart (required) and calendar (optional).

  name: 'list-week-events',
  description: '列出指定周的事件',
  inputSchema: {
    type: 'object',
    properties: {
      weekStart: {
        type: 'string',
        description: '周开始日期，格式：YYYY-MM-DD',
      },
      calendar: {
        type: 'string',
        description: '日历名称',
        default: '工作',
      },
    },
    required: ['weekStart'],
    additionalProperties: false,
  },

• macos-calendar-mcp-v2.js:428-484 (handler)

  Main handler function for 'list-week-events' tool in v2 implementation. Similar to sdk version, uses AppleScript to fetch weekly events.

  // 列出指定周的事件
  listWeekEvents(args) {
    const { weekStart, calendar = "工作" } = args;
    
    const startDate = new Date(weekStart);
    const endDate = new Date(startDate);
    endDate.setDate(startDate.getDate() + 7);
    
    const formattedStart = this.formatDateForAppleScript(weekStart + " 00:00");
    const formattedEnd = this.formatDateForAppleScript(endDate.toISOString().split('T')[0] + " 00:00");
    
    const script = `
      tell application "Calendar"
        set theCalendar to calendar "${calendar}"
        set weekStart to date "${formattedStart}"
        set weekEnd to date "${formattedEnd}"
        
        set weekEvents to every event of theCalendar whose start date ≥ weekStart and start date < weekEnd
        
        set eventList to {}
        repeat with anEvent in weekEvents
          set eventInfo to (summary of anEvent) & "|" & (start date of anEvent) & "|" & (end date of anEvent) & "|" & (location of anEvent)
          set end of eventList to eventInfo
        end repeat
        
        return eventList as string
      end tell
    `;
  
    try {
      const result = execSync(`osascript -e '${script}'`, { encoding: 'utf8' });
      const events = result.trim();
      
      if (!events || events === '""') {
        return {
          content: [{
            type: "text",
            text: `📅 ${calendar} - ${weekStart}这周无事件`
          }]
        };
      }
  
      const eventList = events.split(',').map(event => {
        const [title, start, end, loc] = event.trim().split('|');
        return `📝 ${title}\n🕒 ${start} - ${end}${loc ? `\n📍 ${loc}` : ''}`;
      }).join('\n\n');
  
      return {
        content: [{
          type: "text",
          text: `📅 ${calendar} - ${weekStart}这周的事件:\n\n${eventList}`
        }]
      };
    } catch (error) {
      throw new Error(`获取周事件失败: ${error.message}`);
    }
  }

• macos-calendar-mcp-v2.js:148-166 (schema)

  Input schema for 'list-week-events' tool in v2, specifying weekStart as required string and optional calendar.

    name: "list-week-events",
    description: "列出指定周的事件",
    inputSchema: {
      type: "object",
      properties: {
        weekStart: {
          type: "string",
          description: "周开始日期，格式：YYYY-MM-DD"
        },
        calendar: {
          type: "string",
          description: "日历名称",
          default: "工作"
        }
      },
      required: ["weekStart"],
      additionalProperties: false
    }
  },

• macos-calendar-mcp-sdk.js:244-245 (registration)

  Registration/dispatch in the switch statement for CallToolRequestSchema handler, routing to listWeekEvents.

  case 'list-week-events':
    return await this.listWeekEvents(args);