Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@fantastical show my events for this week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A CLI and MCP server for Fantastical on macOS.
Fantastical keeps its own calendar store that is invisible to Calendar.app and EventKit. This tool bridges the gap by talking to Fantastical directly — via JXA scripting, Apple Shortcuts, and URL schemes — so you can query and create events from the terminal or from any MCP-compatible AI assistant.
macOS with Fantastical installed
Python 3.10+
Related MCP server: MCP Fantastical Server
git clone git@github.com:ramm/fantastical-mcp.git
cd fantastical-mcp
uv syncOn first run, macOS will prompt you to grant permissions. Click Allow when asked:
Automation: your terminal app (Terminal, iTerm, etc.) needs permission to control Fantastical via Apple Events. Triggered by commands like calendars.
Shortcuts: running shortcuts from the terminal may prompt you to allow your terminal to run shortcuts. Triggered by commands like events and search.
These prompts only appear once. If you accidentally deny a permission, you can re-enable it in System Settings > Privacy & Security > Automation (or Shortcuts).
When using the MCP server, the prompts will appear for the MCP host app (e.g. Claude Desktop) instead of your terminal.
# 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"All commands support --json for machine-readable output:
uv run fantastical --json events todaySome features (events by date, search) use Fantastical's App Intents through Apple Shortcuts. Run the guided setup to create the required shortcuts:
uv run fantastical setupThis checks which helper shortcuts are installed and gives step-by-step instructions for any that are missing. You only need to do this once.
Feature | Needs setup? |
List calendars | No |
Create event | No |
Events by date | Yes |
Search events | Yes |
To use fantastical-cli as an MCP server (e.g. with Claude Desktop), start it in stdio mode:
uv run fantastical serveOr add it to your MCP client config:
{
"mcpServers": {
"fantastical": {
"command": "uv",
"args": ["run", "--directory", "/path/to/fantastical-cli", "fantastical", "serve"]
}
}
}The server exposes these tools:
Tool | Description | Response format |
| List all calendars | Plain text, one per line |
| Events in a date range | Compact tab-separated (id, title, start, end, attendeeCount) |
| Search events by title | Same as |
| Create event via natural language | JSON |
| Full details of a cached event | Key-value text with attendees |
| Clear in-memory event/attendee caches | Status message |
List and search results are cached in memory — use get_event_details to retrieve full data (calendar, URL, attendees) for a specific event.
Command | Description |
| List all Fantastical calendars |
| Create event via natural language |
| Today's events |
| Next 7 days (configurable with |
| Events in a date range ( |
| Filter by calendar name |
| Search events by title |
| Create/update helper shortcuts |
| Remove helper shortcuts |
| Start MCP server (stdio) |
macOS doesn't support programmatic shortcut deletion. The uninstall command opens each helper shortcut in Shortcuts.app for you to delete manually:
uv run fantastical uninstallThis project was created by autonomous AI software engineering agents and explicitly reviewed and approved by a human.
Clear the in-memory event and attendee caches.
Use when starting a fresh analysis session.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that it clears caches and specifies which caches (event and attendee). No contradictions or omissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states action, second gives usage. No extraneous words, highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, straightforward action), the description fully covers what it does and when to use. Output schema exists but is not needed to explain behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. The description does not add parameter info, but none needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it clears in-memory event and attendee caches. Distinguishes from sibling tools that are CRUD/list operations, making its utility purpose explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when starting a fresh analysis session,' providing clear context. However, no mention of when not to use or alternative tools, though none exist among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create event using natural language (e.g. 'Meeting tomorrow at 3pm').
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | ||
| calendar | No | ||
| sentence | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only says 'create event using natural language'. It gives no information about permissions, side effects, error conditions, or outcome beyond creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the verb and resource, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description does not mention what the tool returns or how optional parameters (calendar, notes) affect behavior. The example covers only the required parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It explains the 'sentence' parameter via example but offers no detail about 'notes' or 'calendar'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Create event' as the action and resource, and distinguishes from sibling tools that only read or delete events. The example 'Meeting tomorrow at 3pm' reinforces the natural language aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes use case ('using natural language') with a concrete example, but does not explicitly mention when not to use the tool or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details of a cached event by ID.
Returns all fields: title, startDate, endDate, calendar, fantasticalURL, calendarName. Events are cached from previous list_events/search_events calls. Attendees are fetched lazily on first request and cached for the session.
| Name | Required | Description | Default |
|---|---|---|---|
| event_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses caching behavior ('Events are cached from previous...calls') and lazy loading of attendees ('Attendees are fetched lazily on first request and cached for the session'). It also lists returned fields. It does not mention rate limits or permissions, but for a read-only getter that is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each serving a distinct purpose: stating the core function, listing return fields, and explaining caching behavior. There is no redundant information, and the purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (1 param, no nested objects, has output schema), the description covers the essential aspects: what it gets, what fields are returned, and how data is sourced (cached from previous calls, lazy loading). This is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter is 'event_id', which is a required string. The schema coverage is 0%, so the description must add meaning. It does so by clarifying the ID must come from a cached event ('cached event by ID'), implying it is obtained from previous list/search calls. This adds context beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb+resource pair: 'Get full details of a cached event by ID.' It explicitly states the action (get) and the specific entity (cached event details by ID). This distinguishes it from sibling tools like list_events, list_calendars, and search_events, which have different scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that 'Events are cached from previous list_events/search_events calls,' providing clear context on when to use this tool (after listing/searching). It implies the event ID must come from those calls. However, it does not explicitly state when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Fantastical calendars.
Fast and lightweight — no shortcuts required, uses JXA directly. Returns plain text: one calendar per line as "name (id)".
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides key behavioral details: it is fast, uses JXA directly, returns plain text with one calendar per line as 'name (id)'. This sufficiently discloses behavior for a read-only list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each serving a distinct purpose: what it does, performance/implementation note, output format. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an output schema, the description adequately explains the output format. It does not cover error handling, but for a simple list tool it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and schema coverage is 100%. The baseline for no parameters is 4. The description does not need to add parameter info but does explain the output format, which adds value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all Fantastical calendars.' It is a specific verb-resource pair that distinguishes from sibling tools like list_events which lists events, not calendars.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it is the go-to tool for listing calendars but does not explicitly state when to use it vs alternatives. It mentions speed and direct JXA usage, but no clear when-not or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List calendar events in a date range (YYYY-MM-DD).
Accepts 'today', 'tomorrow', 'yesterday', or YYYY-MM-DD. Defaults to today only. Start with 2-week chunks. If results are sparse, increase to months or more.
Returns compact tab-separated output: id, title, startDate, endDate, attendeeCount. All events are cached — use get_event_details for full data (calendar, URL, etc.). Can be called in parallel for different date ranges.
| Name | Required | Description | Default |
|---|---|---|---|
| to_date | No | ||
| calendar | No | ||
| from_date | No | today |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: returns compact tab-separated output (id, title, startDate, endDate, attendeeCount), events are cached, and accepts natural language date strings. No annotations provided, so description carries full burden and does so well, though rate limits or auth are not mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Efficient and well-structured: 4 sentences covering purpose, date syntax, usage strategy, and output format. No redundant information; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While output schema exists to document return structure, the description omits guidance on the 'calendar' parameter, which is critical for filtering. Caching behavior is noted but lacks details like duration. This gap leaves agents potentially misusing the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning for date parameters by specifying accepted formats ('today', 'yesterday', YYYY-MM-DD) and default behavior (today only). However, the 'calendar' parameter is completely undocumented in the description, and the range when to_date is null is ambiguous, leaving gaps despite 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool's purpose: 'List calendar events in a date range.' It uses specific verbs and distinguishes itself from siblings by advising to use get_event_details for full data, indicating this is a compact listing tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Offers concrete usage guidance: start with 2-week chunks, expand if sparse, and mentions it can be called in parallel. Also references get_event_details for full data, but does not explicitly contrast with search_events or other siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search events by title.
Default search window is ±30 days. Override with from_date/to_date (YYYY-MM-DD). Start with 2-week chunks. If results are sparse, increase to months or more. Same compact tab-separated output as list_events with caching. Can be called in parallel for different queries.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| to_date | No | ||
| from_date | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses default date window, output format (tab-separated with caching), and support for parallel calls. No destructive behavior is mentioned, but it appropriately implies read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four sentences, each serving a clear purpose: stating the action, default window, usage strategy, and output characteristics. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, explanation of return values is not needed. The description covers key aspects: search by title, date range control, chunking advice, and output format. Minor omission of error handling or limits prevents a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It explains query (by title), and from_date/to_date (override, YYYY-MM-DD format). It adds meaning beyond schema names, though it does not explicitly mention default null behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches events by title, which is a specific verb+resource. It distinguishes from sibling list_events by mentioning the same output format but search functionality, and indicates default window and parallel calling capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on default window (±30 days), suggests starting with 2-week chunks and expanding, and allows parallel calls. However, it does not explicitly contrast with list_events or other siblings for when to use which.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.2.0clear_cachecreate_eventget_event_detailslist_calendarslist_eventssearch_eventsEach tool serves a distinct purpose: cache management, event creation, event detail retrieval, calendar listing, event listing by date, and event search by title. No two tools have overlapping functionality.
All tool names follow a consistent verb_noun pattern using lowercase and underscores (e.g., list_calendars, search_events), making them predictable and easy to distinguish.
With 6 tools, the set is well-scoped for a calendar event server. Each tool has a clear role, and the count is within the ideal 3-15 range.
The toolset covers event creation and read operations (list, search, get details) and calendar listing, but lacks update and delete functionality for events, and calendar management beyond listing. These are notable gaps for a calendar application.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Calendar API for AI agents: events, availability, Google/Microsoft setup, scheduling, and iCal.
AI-native scheduling: check availability, book meetings, cancel and reschedule via MCP
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
Connects ChatGPT to your Apple Calendar via a local Mac agent + Vercel relay
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ramm/fantastical-cli'
If you have feedback or need assistance with the MCP directory API, please join our Discord server