@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

Related MCP server: MCP Outlook Tools

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)

Write operations (require write scope)

Booking Tools (require book scope)

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

Setup Tools (require full scope)

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.