MCP Calendar Tool Server

A FastAPI-based MCP (Model Context Protocol) server that provides calendar management tools for AI agents running in n8n.

Features

- Server-Sent Events (SSE) for real-time tool discovery
- HTTP endpoints for tool execution
- Calendar management tools:
- Check availability
- Add events
- Update events
- Delete events
- API key authentication
- Mock implementations ready for real calendar API integration

Setup

1. Clone the repository
2. Install dependencies:

   pip install -r requirements.txt

   

3. Create a .env file with your API key:

   API_KEY=your-secret-key-here

   

Running the Server

uvicorn main:app --host 0.0.0.0 --port 5000

API Endpoints

Tool Discovery

- GET /mcp-events - SSE stream of available tools - Used by n8n MCP Client for tool discovery

Tool Execution

- POST /mcp/message - Execute calendar tools - Requires X-API-Key header - Accepts JSON payload with tool name and parameters

Available Tools

Check Availability

{
  "name": "calendar.check_availability",
  "parameters": {
    "start_time": "2024-01-01T10:00:00Z",
    "end_time": "2024-01-01T11:00:00Z"
  }
}

Add Event

{
  "name": "calendar.add_event",
  "parameters": {
    "title": "Meeting",
    "start_time": "2024-01-01T10:00:00Z",
    "end_time": "2024-01-01T11:00:00Z",
    "description": "Team meeting"
  }
}

Update Event

{
  "name": "calendar.update_event",
  "parameters": {
    "event_id": "event_123",
    "title": "Updated Meeting",
    "start_time": "2024-01-01T10:00:00Z",
    "end_time": "2024-01-01T11:00:00Z",
    "description": "Updated team meeting"
  }
}

Delete Event

{
  "name": "calendar.delete_event",
  "parameters": {
    "event_id": "event_123"
  }
}

Development

The project is structured as follows:

/my_mcp_server/
├── main.py              # FastAPI app and routes
├── auth.py             # API key authentication
├── tools/
│   └── calendar.py     # Calendar tool implementations
├── schemas/
│   └── calendar_schemas.py  # Pydantic models
└── requirements.txt    # Python dependencies

Testing

1. Start the server
2. Use the n8n MCP Client node to connect to http://localhost:8000/mcp-events
3. Test tool execution using the /mcp/message endpoint

Future Improvements

- Integration with real calendar APIs (Google Calendar, Cal.com, etc.)
- Enhanced error handling and validation
- Rate limiting and request throttling
- Additional calendar management features
- Webhook support for event notifications