cal-mcp

# 🗓️ Google Calendar MCP Server **I got tired of the Google Cloud setup BS, so I built this.** **Connect your calendar in 30 seconds, not 3 hours.** Skip the OAuth nightmare. No Google Cloud Console. No service accounts. No headaches. Just works with Claude Desktop, Cursor, Zed, or whatever MCP client you're using. ## ✨ Why This Rocks - **🚀 Actually Easy Setup** - 30 seconds vs 3 hours of Google Cloud hell - **🔒 OAuth That Works** - No token management headaches - **🔧 Works Everywhere** - Claude, Cursor, Zed... if it does MCP, we got you - **⚡ Deploy & Forget** - One-click Vercel deployment - **🗓️ Full Calendar Power** - Create, edit, delete events like a boss - **🌐 Your Server** - Host it yourself, own your data - **📱 Test Drive** - Web UI to make sure everything works before going live ## Just Want to Use It? 1. **Connect your calendar:** - Go to https://cal-mcp.com - Hit "Connect Google Calendar" - Do the OAuth dance - Copy your config 2. **Add to your MCP client:** **Option A: Streamable HTTP (Recommended)** ```json { "mcpServers": { "google-calendar": { "url": "https://cal-mcp.com/api/mcp" } } } ``` **Option B: STDIO (Local Server)** ```json { "mcpServers": { "google-calendar": { "command": "npx", "args": ["-y", "mcp-remote", "https://cal-mcp.com/api/mcp"] } } } ``` ## Want to Run Your Own? 1. **Grab the code:** ```bash git clone https://github.com/progrmoiz/cal-mcp cd cal-mcp npm install ``` 2. **Google OAuth setup (yeah, still need this part):** - Hit up [Google Cloud Console](https://console.cloud.google.com/) - Make a project (or use an existing one) - Enable Google Calendar API - Create OAuth 2.0 credentials - Add this redirect URI: `http://localhost:3000/api/auth/callback/google` 3. **Environment variables:** ```bash cp .env.example .env.local ``` Drop in your Google stuff: ``` GOOGLE_CLIENT_ID=your_client_id GOOGLE_CLIENT_SECRET=your_client_secret BETTER_AUTH_SECRET=any_random_string BETTER_AUTH_URL=http://localhost:3000 ``` 4. **Fire it up:** ```bash npm run dev ``` 5. **Connect your calendar:** - Go to http://localhost:3000 - Hit "Connect Google Calendar" - Do the OAuth dance - Copy your config ## 🧪 Test Drive Built-in web interface because who wants to debug blind? - **Play with Events** - Create, edit, delete events right in the browser - **OAuth Testing** - Make sure the auth flow actually works - **Debug Mode** - See raw API responses when things go sideways - **Sanity Check** - Verify everything works before plugging into your AI Hit `http://localhost:3000` once you're running and give it a spin. ## What You Can Do All the calendar stuff you'd expect: - `list-calendars` - See all your calendars - `list-events` - Get events for a date range - `create-event` - Make new events - `update-event` - Change existing events - `delete-event` - Remove events - `search-events` - Find events by text - `get-event` - Get event details - `move-event` - Move events between calendars - `list-colors` - Get color options for calendars/events - `get-freebusy` - Check when you're available - `get-current-time` - Current time and timezone info ## For Builders What's under the hood: - Better Auth handling the OAuth mess - MCP server that actually works - Next.js for the web stuff - TypeScript because we're not animals ## Going Live Ready to deploy? Here's what you need: 1. **Environment Variables** - Set them on your hosting platform 2. **Database** - Point to your Neon PostgreSQL URL 3. **Google OAuth** - Update redirect URIs for your domain 4. **HTTPS** - Because OAuth demands it ## Security Stuff - Better Auth handles tokens so you don't have to - Secrets stay in environment variables where they belong - Everything needs auth (obviously) - Token refresh happens automatically ## 🛠️ When Things Break Stuff not working? Try these: ### Your AI Tool Doesn't Do MCP Not all AI tools support MCP yet. Check if yours does before pulling your hair out. ### Remote Connections Failing Some tools do MCP but hate remote servers. Use the STDIO config instead. ### OAuth Acting Up Did you actually complete the Google login? Try connecting again from the homepage. ### No MCP Support At All Bug your AI tool's developers to add MCP support. The more people ask, the faster it happens. ## 🛠️ Architecture Built with modern technologies for reliability and ease of use: - **Next.js 15** - Full-stack framework with API routes - **Better Auth** - Secure OAuth 2.0 authentication - **MCP Handler** - Model Context Protocol server implementation - **Google Calendar API** - Direct integration with Google's calendar services - **Vercel** - Serverless deployment platform - **TypeScript** - Type-safe development ## 🤝 Want to Help? Contributions welcome! Here's how: 1. **🐛 Found a Bug?** - Open an issue, tell us what broke 2. **💡 Got Ideas?** - Issues are perfect for brainstorming 3. **🔧 Can Code?** - PRs for fixes and features always welcome 4. **📖 Hate Bad Docs?** - Make them better! 5. **🧪 Just Testing?** - Feedback is gold **How to Contribute:** 1. Fork it 2. Branch it: `git checkout -b feature/cool-thing` 3. Code it (and test it!) 4. PR it with a good description **If you want to contribute, here are some ideas worth tackling:** - **📊 Google Sheets MCP** - Spreadsheets meet AI (imagine the possibilities!) - **📧 Gmail MCP** - Email automation that doesn't suck - **☁️ Google Drive MCP** - File management for the AI era - **📝 Google Docs MCP** - Collaborative writing with AI superpowers **Other Calendar Providers:** - **📅 Outlook/Microsoft 365** - Because not everyone lives in Google land - **🍎 Apple Calendar (CalDAV)** - For the Mac enthusiasts Got another idea? **Just build it!** The beauty of this setup is that it's dead simple to extend. Copy the auth flow, swap the API endpoints, and boom - you've got yourself a new MCP server. Feel free to fork this repo and create a pull request. Let's build the future of productivity tools together, one API at a time. 🛠️ ## 📄 License MIT License - do whatever you want with it. ## 💬 Need Help? - **📖 Docs**: This README + code comments - **🐛 Bugs**: GitHub Issues - **💬 Questions**: GitHub Discussions - **📧 Collaboration**: Hit me up