MCP setup
Connect your AI agent.
Let your agent check your agenda and make changes to your calendar. Choose a client and the copy of your calendar it should use.
Connection options
Client
No clients found.
Calendar connection
Use the copy connected in circal Settings.
Mirror file path
Paste the full path reported by --find.
The browser cannot read your file’s full path. This field stays on this page.
Requires Node.js 22.22.3 or later on the computer running your agent. The server runs locally over stdio, including when you use the cloud copy.
Follow these steps
Copy this text manually
Prepare your calendar
Connect a live copy before adding the server.
In circal, open Settings → Cloud. Sign in and unlock your cloud copy with your passphrase. If this is your first time, let circal upload the calendar before continuing.
On the computer running your agent, run the command below. Enter your email, the emailed code and the same passphrase in the terminal. Keep them out of agent chat.
In circal, open Settings → Mirror and connect a .json file. The macOS app creates a default mirror on first launch unless you have disconnected it.
Run the command below. It searches common locations and reports valid mirror files without changing them. Paste your calendar’s full path into the field above. If it finds nothing, use the path of the file you selected in Settings.
Terminalnpx -y circal-mcp@latest loginLogin stores a session and a derived key on this computer. It never stores or sends your passphrase.
The agent can use the file while circal is closed. Keep Mirror connected when you open circal so changes can sync back.
Configure your client
For omp
Add this configuration to .omp/mcp.json in your project. Merge circal into mcpServers if the file already contains servers.
Enter your mirror file path above before copying this configuration.
.omp/mcp.json{ "mcpServers": { "circal": { "type": "stdio", "command": "npx", "args": [ "-y", "circal-mcp@latest", "--cloud" ] } } }For all projects, use ~/.omp/agent/mcp.json. Named profiles use ~/.omp/profiles/<name>/agent/mcp.json. PI_CONFIG_DIR and PI_CODING_AGENT_DIR can change these locations.
View omp docs ↗Check the connection
Confirm the right calendar before making changes.
Run /mcp reload in omp, followed by /mcp list to check the connection.
Ask your agent to call sync_status. Check the connection type, timezone and record counts against your calendar.
Ask your agentCall circal’s sync_status and tell me the transport, timezone and record counts. Do not change anything.Install the circal skill (optional)
Give your agent instructions for using the calendar tools.
The circal skill explains how to check the connection, work with events and tasks, and handle recurring events without changing the wrong occurrences. It adds instructions, not calendar access; the MCP connection above is still required.
Terminalnpx skills add VSHT3/circal --skill circalChoose your agent in the installer and the scope you want. If it is not listed, follow your client’s skill installation instructions and copy the complete
Read the circal skill ↗skills/circalfolder, including its references. Some clients do not support skills.
Try it with your calendar
Start with a question. Review the date and calendar before approving a change.
- “What’s on Thursday?”
- “Find me an hour free tomorrow afternoon.”
- “Book dentist next Tuesday at 2.”
- “Move my standup to 10.”
What you’re giving access to
The server can read and change your own events and tasks. Cloud storage holds encrypted data, but your agent receives readable results from the server. Your AI provider’s data policy applies to those results.
- Subscribed calendars stay read-only. Their feed events are not in the connected copy, so availability checks cannot account for them. Editing or deleting a repeating event requires an explicit scope: one occurrence, future occurrences or the whole series.
- Writes are refused when the server’s timezone differs from the calendar’s recorded timezone, unless you explicitly override that guard.
- Cloud setup requires an existing account and uploaded copy. The MCP server does not create either.
- There is no server-wide read-only setting. Use your client’s tool permissions to restrict changes.
Disconnect a file
Remove circal from your client’s MCP configuration and stop its server. Disconnecting Mirror in circal stops app sync; it does not revoke access to the file. Protect or remove that file separately.
Disconnect the cloud copy
Run npx -y circal-mcp@latest logout to remove this machine’s saved session and key. Remove circal from your client’s configuration too. Anyone who can read the credentials file can access your calendar.