OpenSlot MCP
Allows querying Google Calendar ICS feeds to retrieve busy/free availability and find open meeting slots.
Allows querying iCloud calendars through public webcal:// ICS feeds to retrieve busy/free availability and find open meeting slots.
Click on "Deploy 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., "@OpenSlot MCP What free slots do I have tomorrow between 9am and 5pm?"
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.
OpenSlot MCP
A read-only Model Context Protocol server that turns one or more Outlook, iCloud, or Google calendars into privacy-safe availability queries. It accepts HTTPS ICS feeds and iCloud-style webcal:// subscription links.
It intentionally never returns event titles, descriptions, locations, attendees, organizers, or raw calendar data — only busy/free time intervals.
Requirements
Node.js 20.6 or newer.
An HTTPS or
webcal://URL to an ICS calendar feed.
No installation is needed: MCP clients can launch the server straight from this repository with npx -y github:YHRen/openslot-mcp. The first launch clones and builds the package (expect several seconds); after that it runs from the npx cache. To get reproducible installs, pin a tag or commit, e.g. github:YHRen/openslot-mcp#v0.1.0.
Related MCP server: when-free
Get a calendar URL
The server uses each provider's read-only calendar feed. It does not ask for account credentials or request write access.
Provider | How to get the ICS feed | Typical allowlist host |
Outlook / Microsoft 365 | In Outlook on the web, open Calendar → View → Calendar settings → Calendar → Shared calendars. Under Publish a calendar, select a calendar and permission level, select Publish, then copy the ICS link. Choose busy-only visibility when available. Microsoft instructions |
|
iCloud Calendar | On a computer or tablet, open Calendar on iCloud.com, select the calendar's information button, turn on Public Calendar, then select Copy. Use the copied | The exact numbered host in the link, such as |
Google Calendar | On a computer, open Settings → Settings for my calendars → calendar name → Integrate calendar, then copy Secret address in iCal format. For an intentionally public calendar, its Public address in iCal format also works. Google instructions |
|
iCloud's public-calendar option makes the calendar readable to anyone who has its link; private iCloud shares are not anonymous ICS feeds and are not supported. Google Workspace administrators may disable secret iCal addresses.
Connect an MCP client
Claude Code:
claude mcp add openslot \
--env CALENDAR_ICS_URL="https://outlook.office365.com/owa/calendar/<token>/calendar.ics" \
--env CALENDAR_ALLOWED_HOSTS="outlook.office365.com" \
-- npx -y github:YHRen/openslot-mcpClaude Desktop (claude_desktop_config.json) and other JSON-configured hosts:
{
"mcpServers": {
"openslot": {
"command": "npx",
"args": ["-y", "github:YHRen/openslot-mcp"],
"env": {
"CALENDAR_ICS_URL": "https://outlook.office365.com/owa/calendar/<token>/calendar.ics",
"CALENDAR_ALLOWED_HOSTS": "outlook.office365.com"
}
}
}
}OpenAI Codex CLI (~/.codex/config.toml):
[mcp_servers.openslot]
command = "npx"
args = ["-y", "github:YHRen/openslot-mcp"]
[mcp_servers.openslot.env]
CALENDAR_ICS_URL = "https://outlook.office365.com/owa/calendar/<token>/calendar.ics"
CALENDAR_ALLOWED_HOSTS = "outlook.office365.com"Google Antigravity (agy CLI and IDE) — add to the shared ~/.gemini/config/mcp_config.json, or .agents/mcp_config.json to scope it to one workspace:
{
"mcpServers": {
"openslot": {
"command": "npx",
"args": ["-y", "github:YHRen/openslot-mcp"],
"env": {
"CALENDAR_ICS_URL": "https://outlook.office365.com/owa/calendar/<token>/calendar.ics",
"CALENDAR_ALLOWED_HOSTS": "outlook.office365.com"
}
}
}
}Other MCP hosts follow the same pattern: launch npx -y github:YHRen/openslot-mcp over stdio with the CALENDAR_* environment variables set.
Replace the sample Outlook URL with the iCloud or Google URL you copied. Set CALENDAR_ALLOWED_HOSTS to the exact hostname in that URL—for example, calendar.google.com for Google or the numbered p…-caldav.icloud.com hostname present in an iCloud link.
To combine providers, configure multiple named feeds:
[
{ "id": "work", "url": "https://outlook.office365.com/owa/calendar/<token>/calendar.ics" },
{ "id": "personal", "url": "webcal://p123-caldav.icloud.com/published/2/<token>" },
{ "id": "family", "url": "https://calendar.google.com/calendar/ical/<calendar-and-token>/basic.ics" }
]Pass the compact JSON as CALENDARS_JSON and set CALENDAR_ALLOWED_HOSTS=outlook.office365.com,p123-caldav.icloud.com,calendar.google.com.
To sanity-check your calendar URL outside a client, run the server directly — it speaks MCP over stdio, so it will sit waiting for a client; starting without an error means the configuration is valid (Ctrl-C to exit):
CALENDAR_ICS_URL="https://…/calendar.ics" npx -y github:YHRen/openslot-mcpTools
get_availability(start, end, timezone?, calendars?, includeTentative?): merged busy intervals only.find_free_slots(start, end, durationMinutes, timezone?, calendars?, includeTentative?, bufferMinutes?, workingHours?): openings matching a required duration, working hours, and optional meeting buffer.get_calendar_status(): cache/source health without event content.
Example — find_free_slots with {"start": "2026-09-01T00:00:00-04:00", "end": "2026-09-03T00:00:00-04:00", "durationMinutes": 30} returns:
{
"timezone": "America/New_York",
"start": "2026-09-01T00:00:00-04:00",
"end": "2026-09-03T00:00:00-04:00",
"durationMinutes": 30,
"slots": [
{ "start": "2026-09-01T10:00:00-04:00", "end": "2026-09-01T11:00:00-04:00", "durationMinutes": 60 }
]
}Queries use offset-bearing ISO-8601 input timestamps, output the caller's requested IANA timezone, and are capped at 90 days. All-day and floating (TZID-less) events are interpreted in the requested timezone. ICS refreshes are cached for five minutes by default and use conditional HTTP requests when the provider supports them. If a refresh fails, cached data is served with a staleCalendars field in the response and retries are backed off for 30 seconds.
Configuration
Set environment variables through your MCP host's env block (or .env for local runs):
CALENDAR_ICS_URL— a single HTTPS orwebcal://calendar feed.CALENDARS_JSON— multiple named calendars, including feeds from different providers. Takes precedence overCALENDAR_ICS_URL.CALENDAR_ALLOWED_HOSTS— optional comma-separated host allowlist; strongly recommended.CALENDAR_CACHE_TTL_SECONDS— feed cache lifetime, default300.CALENDAR_DEFAULT_TIMEZONE— IANA timezone used when a query does not specify one, defaultAmerica/New_York.
Privacy and security
A published ICS URL—including Google's Secret address—acts like a bearer credential: anyone with it may read the calendar view. Store it only in secret or local environment configuration, do not commit it, and rotate/revoke it if exposed. The server converts webcal:// links to HTTPS, rejects embedded URL credentials and non-443 ports, validates every redirect hop against the same rules and the host allowlist, restricts feed size to 5 MiB, and does not log the source URL or calendar contents.
Development
git clone https://github.com/YHRen/openslot-mcp.git
cd openslot-mcp
npm install # also compiles dist/ via the prepare script
cp .env.example .env # put your calendar URL in .env (do not commit it)
npm test # vitest, synthetic fixtures only
npm run check # typecheck
npm run build # compile to dist/
node --env-file=.env dist/index.js # run the built server
node --env-file=.env --import tsx src/index.ts # run from sourceTo point an MCP client at a local checkout instead of the npm package, use node /absolute/path/to/openslot-mcp/dist/index.js as the command.
Available Tools
3 toolsfind_free_slotsC
Find privacy-safe free intervals across configured calendars during stated working hours.
Inputs: end (required), start (required), durationMinutes (required), timezone, +4 more. Returns: end, slots, start, timezone, +2 more
get_availabilityA
Return privacy-safe busy intervals for the configured calendars. Event names, locations, attendees, and notes are never returned.
Inputs: end (required), start (required), timezone, calendars, +1 more. Returns: end, busy, start, timezone, +1 more
get_calendar_statusA
Return source-health and cache metadata only; it does not reveal calendar content.
Inputs: no named parameters. Returns: calendars
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool serves a clearly distinct purpose: one returns busy intervals, one returns free slots, and one returns only health/cache metadata. There is no overlap in what an agent would select them for.
All three tool names follow a consistent lowercase snake_case verb_noun pattern: get_availability, find_free_slots, get_calendar_status. The pattern is predictable and readable across the set.
Three tools is a well-scoped size for a focused calendar-availability server. Each tool maps to a distinct operation an agent would need, with no redundancy or bloat.
For the stated purpose of privacy-safe availability, the server covers the essential operations: busy intervals, free slots, and source/cache health. There are no obvious dead ends or missing core capabilities within this narrow domain.
Maintenance
Related MCP Connectors
Merged free/busy, find mutual time, propose bookings with human approval. Never event contents.
Read-only view of all your calendars (Google, Outlook, Zoho, iCloud): agenda and free time
Calendar API for AI agents: events, availability, Google/Microsoft setup, scheduling, and iCal.
Read and change Google Calendar and Outlook events, find free time and add meeting links.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables full CRUD operations on calendar events, free/busy queries, and availability slot finding via CalDAV, supporting Nextcloud, Radicale, iCloud, and other RFC 4791-compliant servers.8MIT
- AlicenseNot gradedqualityBmaintenanceEnables assistants and agents to query calendar availability from Google, Outlook, iCloud, or ICS feeds and return free time slots for specified days, date ranges, or pasted messages. It exposes read-only tools for finding availability and checking calendar readability without exposing calendar addresses.24 PyPIApache 2.0
- AlicenseNot gradedqualityBmaintenanceLets an AI assistant check your availability by reading private ICS subscription feeds and returning merged busy intervals or open free slots, while keeping event titles, notes, attendees, and feed URLs entirely on the server. Access is read-only and protected by OAuth with a single-account allowlist.MIT
- AlicenseNot gradedqualityCmaintenanceGives AI agents read-only access to any number of iCal (.ics) calendar feeds, letting them list calendars, read and search events with recurring series expanded, and find free time. Runs statelessly from a single YAML config with bearer-token auth, keeping feed URLs secret.MIT