AI导哈

Fantastical 命令行工具

一个用于在 macOS 上通过命令行或 MCP 兼容的 AI 助手查询和创建 Fantastical 日历事件的工具。

  • by ramm
  • Python
  • 本地部署
  • 5 星标
  • 更新于
在 GitHub 查看 ramm/fantastical-cli

使用说明

梦幻般的mcp

CLI和 MCP服务器 为了 奇幻的 在macOS上。

Fantastical拥有自己的日历存储，calendar.app和EventKit无法访问。该工具通过直接与Fantastical对话（通过JXA脚本、Apple快捷方式和URL方案）来弥合差距，因此您可以从终端或任何兼容MCP的AI助手查询和创建事件。

需求

  • 安装了Fantastical的macOS
  • Python 3.10+
  • 紫外线

安装

git clone git@github.com:ramm/fantastical-mcp.git
cd fantastical-mcp
uv sync

macOS权限

首次运行时，macOS会提示您授予权限。点击 允许 当被问及：

  • 自动化：您的终端应用程序（terminal、iTerm等）需要获得许可才能通过Apple Events控制Fantastical。由以下命令触发 calendars.
  • 捷径：从终端运行快捷键可能会提示您允许终端运行快捷方式。由以下命令触发 events 和 search.

这些提示只出现一次。如果您意外拒绝了权限，可以在中重新启用它 系统设置>隐私和安全>自动化 （或 捷径).

使用MCP服务器时，提示将出现在MCP主机应用程序（例如Claude Desktop）上，而不是您的终端上。

快速开始

# List your calendars (works immediately, no setup needed)
uv run fantastical calendars

# Create an event using natural language
uv run fantastical add "Lunch with Alex tomorrow at noon"

# Set up helper shortcuts (one-time, needed for events/search)
uv run fantastical setup

# After setup — list today's events
uv run fantastical events today

# Upcoming events for the next 7 days
uv run fantastical events upcoming

# Search events by title
uv run fantastical search "standup"

所有命令支持 --json 对于机器可读输出：

uv run fantastical --json events today

设置

一些功能（按日期事件、搜索）通过苹果快捷方式使用Fantastical的应用程序意图。运行指导设置以创建所需的快捷方式：

uv run fantastical setup

这将检查安装了哪些帮助快捷方式，并为缺少的快捷方式提供分步说明。你只需要做一次。

功能 需要设置吗？
列出日历 否
创建事件 否
按日期列出的事件 是
搜索事件 是

MCP服务器

要将fantastical cli用作MCP服务器（例如使用Claude Desktop），请在stdio模式下启动它：

uv run fantastical serve

或者将其添加到MCP客户端配置中：

{
  "mcpServers": {
    "fantastical": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/fantastical-cli", "fantastical", "serve"]
    }
  }
}

服务器公开了这些工具：

工具 描述 响应格式
list_calendars 列出所有日历 纯文本，每行一个
list_events 日期范围内的事件 压缩选项卡分隔（id、标题、开始、结束、与会者计数）
search_events 按标题搜索事件 与 list_events
create_event 通过自然语言创建事件 JSON
get_event_details 缓存事件的完整详细信息 与会者的键值文本
clear_cache 清除内存中的事件/与会者缓存 状态消息

列表和搜索结果缓存在内存中--使用 get_event_details 检索特定事件的完整数据（日历、URL、与会者）。

CLI参考

命令 描述
calendars 列出所有幻想日历
add "..." 通过自然语言创建事件
events today 今天的活动
events upcoming 未来7天（可配置 --days)
events list 日期范围内的事件(--from, --to)
events --calendar "X" 按日历名称筛选
search <query> 按标题搜索事件
setup [--force] 创建/更新辅助快捷方式
uninstall 删除帮助快捷方式
serve 启动MCP服务器（stdio）

卸载快捷方式

macOS不支持程序化快捷方式删除。卸载命令打开Shortcuts.app中的每个帮助快捷方式，供您手动删除：

uv run fantastical uninstall

作者身份

该项目由自主AI软件工程代理创建，并由人类明确审查和批准。

许可证

麻省理工学院

相关 MCP