@calmesh/mcp-server

MCP server for CalMesh — AI-first calendar infrastructure. Connects AI agents to your calendars, bookings, and scheduling polls via the Model Context Protocol.

Quick Start

CALMESH_API_KEY=cm_live_... npx @calmesh/mcp-server

Setup

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "calmesh": {
      "command": "npx",
      "args": ["@calmesh/mcp-server"],
      "env": {
        "CALMESH_API_KEY": "cm_live_your_key_here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "calmesh": {
      "command": "npx",
      "args": ["@calmesh/mcp-server"],
      "env": {
        "CALMESH_API_KEY": "cm_live_your_key_here"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "calmesh": {
      "command": "npx",
      "args": ["@calmesh/mcp-server"],
      "env": {
        "CALMESH_API_KEY": "cm_live_your_key_here"
      }
    }
  }
}

Available Tools

Core Tools

Read operations (require read scope)

Tool	Description
calmesh_list_calendars	List all unified calendars
calmesh_get_events	Get events within a date range
calmesh_get_event_details	Get full event details (title, description, location)
calmesh_check_availability	Check available time slots
calmesh_find_conflicts	Find overlapping events

Write operations (require write scope)

Tool	Description
calmesh_create_event	Create a calendar event
calmesh_delete_event	Delete a calendar event

Booking Tools (require book scope)

Tool	Description
calmesh_get_slots	Get available booking slots
calmesh_create_booking	Create a new booking
calmesh_cancel_booking	Cancel a booking
calmesh_list_bookings	List bookings with pagination

Poll Tools (require book scope for create/decide, read for list/overlap)

Tool	Description
calmesh_create_poll	Create a scheduling poll
calmesh_list_polls	List all polls
calmesh_get_poll_overlap	Get participant overlap
calmesh_decide_poll	Finalize poll with chosen time

Setup Tools (require full scope)

Tool	Description
calmesh_start_oauth_connection	Connect Google or Microsoft calendar
calmesh_start_credential_connection	Connect CalDAV or iCal URL
calmesh_check_connection_status	Check connection sync status
calmesh_list_connections	List all connections
calmesh_remove_connection	Remove a connection
calmesh_create_calendar	Create unified calendar with sources
calmesh_manage_calendar	Update calendar, manage sources

HTTP Transport

For remote or hosted MCP clients, use the HTTP transport:

CALMESH_API_KEY=cm_live_... \
CALMESH_HTTP_SECRET=your_secret_token \
npx @calmesh/mcp-server --transport http --port 3100

The server binds to 127.0.0.1 by default. All requests must include Authorization: Bearer <http-secret>.

CLI Options

--api-key <key>       CalMesh API key (prefer CALMESH_API_KEY env var)
--base-url <url>      API base URL (default: https://calmesh.xyz)
--transport <type>    stdio (default) or http
--port <port>         HTTP port (default: 3100)
--host <host>         HTTP host (default: 127.0.0.1)
--http-secret <token> Required for HTTP transport
--help                Show help
--version             Show version

Troubleshooting

"Invalid or expired API key" Generate a new API key at calmesh.xyz/dashboard/api-keys.

"Insufficient permissions" Your API key scope is too low. Core tools need read, booking tools need book, setup tools need full.

"Rate limit exceeded" Wait a moment and retry.

"Unable to reach CalMesh API" Check your network connection and --base-url value.

"CalMesh API request timed out" Requests time out after 30 seconds. Retry or check service status.

HTTP transport "Unauthorized" Ensure your client sends Authorization: Bearer <http-secret> with every request.