@iflow-mcp/v-3-google-calendar 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 v-3
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,329 @@
+# Google Calendar MCP Server
+
+This MCP server allows Claude to interact with your Google Calendar, enabling capabilities like listing events, creating meetings, and finding free time slots.
+
+## Prerequisites
+
+- Node.js (v16 or higher)
+- Claude Desktop App
+- A Google Cloud Project
+- Google Calendar API enabled
+- OAuth 2.0 credentials
+
+## Setup Instructions
+
+### 1. Create a Google Cloud Project
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select an existing one
+3. Enable the Google Calendar API:
+   - Go to "APIs & Services" > "Library"
+   - Search for "Google Calendar API"
+   - Click "Enable"
+
+### 2. Configure OAuth Consent Screen
+
+1. Go to "APIs & Services" > "OAuth consent screen"
+2. Select "External" user type (unless you have a Google Workspace organization)
+3. Fill in the required information:
+   - App name
+   - User support email
+   - Developer contact information
+4. Add the following scopes:
+   - `https://www.googleapis.com/auth/calendar`
+   - `https://www.googleapis.com/auth/calendar.events`
+5. Add your email address as a test user
+
+### 3. Create OAuth 2.0 Credentials
+
+1. Go to "APIs & Services" > "Credentials"
+2. Click "Create Credentials" > "OAuth client ID"
+3. Select "Desktop app" as the application type
+4. Name your client (e.g., "MCP Calendar Client")
+5. Click "Create"
+6. Download the client configuration file (you'll need the client ID and client secret)
+
+### 4. Get Refresh Token
+
+1. Create a new file named `getToken.js`:
+
+```javascript
+const { google } = require('googleapis');
+const http = require('http');
+const url = require('url');
+
+// Replace these with your OAuth 2.0 credentials
+const CLIENT_ID = 'your-client-id';
+const CLIENT_SECRET = 'your-client-secret';
+const REDIRECT_URI = 'http://localhost:3000/oauth2callback';
+
+// Configure OAuth2 client
+const oauth2Client = new google.auth.OAuth2(
+  CLIENT_ID,
+  CLIENT_SECRET,
+  REDIRECT_URI
+);
+
+// Define scopes
+const scopes = [
+  'https://www.googleapis.com/auth/calendar',
+  'https://www.googleapis.com/auth/calendar.events'
+];
+
+async function getRefreshToken() {
+  return new Promise((resolve, reject) => {
+    try {
+      // Create server to handle OAuth callback
+      const server = http.createServer(async (req, res) => {
+        try {
+          const queryParams = url.parse(req.url, true).query;
+          
+          if (queryParams.code) {
+            // Get tokens from code
+            const { tokens } = await oauth2Client.getToken(queryParams.code);
+            console.log('\n=================');
+            console.log('Refresh Token:', tokens.refresh_token);
+            console.log('=================\n');
+            console.log('Save this refresh token in your configuration!');
+            
+            // Send success response
+            res.end('Authentication successful! You can close this window.');
+            
+            // Close server
+            server.close();
+            resolve(tokens);
+          }
+        } catch (error) {
+          console.error('Error getting tokens:', error);
+          res.end('Authentication failed! Please check console for errors.');
+          reject(error);
+        }
+      }).listen(3000, () => {
+        // Generate auth url
+        const authUrl = oauth2Client.generateAuthUrl({
+          access_type: 'offline',
+          scope: scopes,
+          prompt: 'consent'  // Force consent screen to ensure refresh token
+        });
+
+        console.log('1. Copy this URL and paste it in your browser:');
+        console.log('\n', authUrl, '\n');
+        console.log('2. Follow the Google authentication process');
+        console.log('3. Wait for the refresh token to appear here');
+      });
+
+    } catch (error) {
+      console.error('Server creation error:', error);
+      reject(error);
+    }
+  });
+}
+
+// Run the token retrieval
+getRefreshToken().catch(console.error);
+```
+
+2. Install required dependency:
+```bash
+npm install googleapis
+```
+
+3. Update the script with your OAuth credentials:
+   - Replace `your-client-id` with your actual client ID
+   - Replace `your-client-secret` with your actual client secret
+
+4. Run the script:
+```bash
+node getToken.js
+```
+
+5. Follow the instructions in the console:
+   - Copy the provided URL
+   - Paste it into your browser
+   - Complete the Google authentication process
+   - Copy the refresh token that appears in the console
+
+### 5. Configure Claude Desktop
+
+1. Open your Claude Desktop configuration file:
+
+**For MacOS:**
+```bash
+code ~/Library/Application\ Support/Claude/claude_desktop_config.json
+```
+
+**For Windows:**
+```bash
+code %AppData%\Claude\claude_desktop_config.json
+```
+
+2. Add or update the configuration:
+```json
+{
+    "mcpServers": {
+        "google-calendar": {
+            "command": "node",
+            "args": [
+                "/ABSOLUTE/PATH/TO/YOUR/build/index.js"
+            ],
+            "env": {
+                "GOOGLE_CLIENT_ID": "your_client_id_here",
+                "GOOGLE_CLIENT_SECRET": "your_client_secret_here",
+                "GOOGLE_REDIRECT_URI": "http://localhost",
+                "GOOGLE_REFRESH_TOKEN": "your_refresh_token_here"
+            }
+        }
+    }
+}
+```
+
+3. Save the file and restart Claude Desktop
+
+## Initial Project Setup
+
+1. Create a new directory for your project:
+```bash
+mkdir google-calendar-mcp
+cd google-calendar-mcp
+```
+
+2. Initialize a new npm project:
+```bash
+npm init -y
+```
+
+3. Install dependencies:
+```bash
+npm install @modelcontextprotocol/sdk googleapis google-auth-library zod
+npm install -D @types/node typescript
+```
+
+4. Create a tsconfig.json file:
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./build",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}
+```
+
+5. Update package.json:
+```json
+{
+  "type": "module",
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\""
+  }
+}
+```
+
+6. Create your source directory:
+```bash
+mkdir src
+```
+
+7. Create a .env file for local development (don't commit this file):
+```bash
+GOOGLE_CLIENT_ID=your_client_id_here
+GOOGLE_CLIENT_SECRET=your_client_secret_here
+GOOGLE_REDIRECT_URI=http://localhost
+GOOGLE_REFRESH_TOKEN=your_refresh_token_here
+```
+
+## Building and Running
+
+1. Build the server:
+```bash
+npm run build
+```
+
+2. The server will automatically start when you open Claude Desktop
+
+## Available Tools
+
+The server provides the following tools:
+
+1. `list_events`: List calendar events within a specified time range
+2. `create_event`: Create a new calendar event
+3. `update_event`: Update an existing calendar event
+4. `delete_event`: Delete a calendar event
+5. `find_free_time`: Find available time slots in the calendar
+
+## Example Usage in Claude
+
+After setup, you can use commands like:
+
+- "Show me my calendar events for next week"
+- "Schedule a meeting with [email_id] tomorrow at 2 PM for 1 hour"
+- "Find a free 30-minute slot this afternoon"
+- "Update my 3 PM meeting to 4 PM"
+- "Cancel my meeting with ID [event_id]"
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Tools not appearing in Claude:**
+   - Check Claude Desktop logs: `tail -f ~/Library/Logs/Claude/mcp*.log`
+   - Verify all environment variables are set correctly
+   - Ensure the path to index.js is absolute and correct
+
+2. **Authentication Errors:**
+   - Verify your OAuth credentials are correct
+   - Check if refresh token is valid
+   - Ensure required scopes are enabled
+
+3. **Server Connection Issues:**
+   - Check if the server built successfully
+   - Verify file permissions on build/index.js (should be 755)
+   - Try running the server directly: `node /path/to/build/index.js`
+
+### Viewing Logs
+
+To view server logs:
+```bash
+# For MacOS/Linux:
+tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
+
+# For Windows:
+Get-Content -Path "$env:AppData\Claude\Logs\mcp*.log" -Wait -Tail 20
+```
+
+### Environment Variables
+
+If you're getting environment variable errors, verify each one:
+
+1. GOOGLE_CLIENT_ID: Should start with something like "123456789-..."
+2. GOOGLE_CLIENT_SECRET: Usually ends in ".apps.googleusercontent.com"
+3. GOOGLE_REDIRECT_URI: Should be "http://localhost"
+4. GOOGLE_REFRESH_TOKEN: A long string that doesn't expire
+
+## Security Considerations
+
+- Keep your OAuth credentials secure
+- Don't commit credentials to version control
+- Use environment variables for sensitive data
+- Regularly rotate refresh tokens
+- Monitor API usage in Google Cloud Console
+
+## License
+
+MIT License - See LICENSE file for details.
+
+## Support
+
+If you encounter any issues:
+1. Check the troubleshooting section above
+2. Review Claude Desktop logs
+3. Open an issue on GitHub
+4. Contact the maintainer

package/build/index.js

@@ -0,0 +1,392 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { google } from 'googleapis';
+import { OAuth2Client } from 'google-auth-library';
+// Initialize Google Calendar client
+const oauth2Client = new OAuth2Client({
+    clientId: process.env.GOOGLE_CLIENT_ID,
+    clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+    redirectUri: process.env.GOOGLE_REDIRECT_URI,
+});
+// Set credentials from environment variables
+oauth2Client.setCredentials({
+    refresh_token: process.env.GOOGLE_REFRESH_TOKEN,
+});
+const calendar = google.calendar({ version: 'v3', auth: oauth2Client });
+// Validation schemas
+const schemas = {
+    toolInputs: {
+        listEvents: z.object({
+            timeMin: z.string().optional(),
+            timeMax: z.string().optional(),
+            maxResults: z.number().optional(),
+        }),
+        createEvent: z.object({
+            summary: z.string(),
+            description: z.string().optional(),
+            startTime: z.string(),
+            endTime: z.string(),
+            attendees: z.array(z.string()).optional(),
+        }),
+        updateEvent: z.object({
+            eventId: z.string(),
+            summary: z.string().optional(),
+            description: z.string().optional(),
+            startTime: z.string().optional(),
+            endTime: z.string().optional(),
+        }),
+        deleteEvent: z.object({
+            eventId: z.string(),
+        }),
+        findFreeTime: z.object({
+            timeMin: z.string(),
+            timeMax: z.string(),
+            duration: z.number(), // duration in minutes
+        })
+    }
+};
+// Tool definitions
+const TOOL_DEFINITIONS = [
+    {
+        name: "list_events",
+        description: "List calendar events within a specified time range",
+        inputSchema: {
+            type: "object",
+            properties: {
+                timeMin: {
+                    type: "string",
+                    description: "Start time (ISO string)",
+                },
+                timeMax: {
+                    type: "string",
+                    description: "End time (ISO string)",
+                },
+                maxResults: {
+                    type: "number",
+                    description: "Maximum number of events to return",
+                },
+            },
+        },
+    },
+    {
+        name: "create_event",
+        description: "Create a new calendar event",
+        inputSchema: {
+            type: "object",
+            properties: {
+                summary: {
+                    type: "string",
+                    description: "Event title",
+                },
+                description: {
+                    type: "string",
+                    description: "Event description",
+                },
+                startTime: {
+                    type: "string",
+                    description: "Event start time (ISO string)",
+                },
+                endTime: {
+                    type: "string",
+                    description: "Event end time (ISO string)",
+                },
+                attendees: {
+                    type: "array",
+                    items: {
+                        type: "string",
+                    },
+                    description: "List of attendee email addresses",
+                },
+            },
+            required: ["summary", "startTime", "endTime"],
+        },
+    },
+    {
+        name: "update_event",
+        description: "Update an existing calendar event",
+        inputSchema: {
+            type: "object",
+            properties: {
+                eventId: {
+                    type: "string",
+                    description: "ID of the event to update",
+                },
+                summary: {
+                    type: "string",
+                    description: "New event title",
+                },
+                description: {
+                    type: "string",
+                    description: "New event description",
+                },
+                startTime: {
+                    type: "string",
+                    description: "New start time (ISO string)",
+                },
+                endTime: {
+                    type: "string",
+                    description: "New end time (ISO string)",
+                },
+            },
+            required: ["eventId"],
+        },
+    },
+    {
+        name: "delete_event",
+        description: "Delete a calendar event",
+        inputSchema: {
+            type: "object",
+            properties: {
+                eventId: {
+                    type: "string",
+                    description: "ID of the event to delete",
+                },
+            },
+            required: ["eventId"],
+        },
+    },
+    {
+        name: "find_free_time",
+        description: "Find available time slots in the calendar",
+        inputSchema: {
+            type: "object",
+            properties: {
+                timeMin: {
+                    type: "string",
+                    description: "Start of time range (ISO string)",
+                },
+                timeMax: {
+                    type: "string",
+                    description: "End of time range (ISO string)",
+                },
+                duration: {
+                    type: "number",
+                    description: "Desired duration in minutes",
+                },
+            },
+            required: ["timeMin", "timeMax", "duration"],
+        },
+    },
+];
+// Tool implementation handlers
+const toolHandlers = {
+    async list_events(args) {
+        const { timeMin, timeMax, maxResults = 10 } = schemas.toolInputs.listEvents.parse(args);
+        const response = await calendar.events.list({
+            calendarId: 'primary',
+            timeMin: timeMin || new Date().toISOString(),
+            timeMax,
+            maxResults,
+            singleEvents: true,
+            orderBy: 'startTime',
+        });
+        const events = response.data.items || [];
+        const formattedEvents = events.map(event => {
+            return `• ${event.summary}\n  Start: ${event.start?.dateTime || event.start?.date}\n  End: ${event.end?.dateTime || event.end?.date}\n  ID: ${event.id}`;
+        }).join('\n\n');
+        return {
+            content: [{
+                    type: "text",
+                    text: events.length ?
+                        `Found ${events.length} events:\n\n${formattedEvents}` :
+                        "No events found in the specified time range."
+                }]
+        };
+    },
+    async create_event(args) {
+        const { summary, description, startTime, endTime, attendees } = schemas.toolInputs.createEvent.parse(args);
+        const event = await calendar.events.insert({
+            calendarId: 'primary',
+            requestBody: {
+                summary,
+                description,
+                start: {
+                    dateTime: startTime,
+                    timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+                },
+                end: {
+                    dateTime: endTime,
+                    timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+                },
+                attendees: attendees?.map(email => ({ email })),
+            },
+        });
+        return {
+            content: [{
+                    type: "text",
+                    text: `Event created successfully!\nID: ${event.data.id}\nLink: ${event.data.htmlLink}`
+                }]
+        };
+    },
+    async update_event(args) {
+        const { eventId, summary, description, startTime, endTime } = schemas.toolInputs.updateEvent.parse(args);
+        // Get existing event
+        const existingEvent = await calendar.events.get({
+            calendarId: 'primary',
+            eventId,
+        });
+        // Prepare update payload
+        const updatePayload = {
+            summary: summary || existingEvent.data.summary,
+            description: description || existingEvent.data.description,
+        };
+        if (startTime) {
+            updatePayload.start = {
+                dateTime: startTime,
+                timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+            };
+        }
+        if (endTime) {
+            updatePayload.end = {
+                dateTime: endTime,
+                timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+            };
+        }
+        await calendar.events.update({
+            calendarId: 'primary',
+            eventId,
+            requestBody: updatePayload,
+        });
+        return {
+            content: [{
+                    type: "text",
+                    text: `Event ${eventId} updated successfully!`
+                }]
+        };
+    },
+    async delete_event(args) {
+        const { eventId } = schemas.toolInputs.deleteEvent.parse(args);
+        await calendar.events.delete({
+            calendarId: 'primary',
+            eventId,
+        });
+        return {
+            content: [{
+                    type: "text",
+                    text: `Event ${eventId} deleted successfully!`
+                }]
+        };
+    },
+    async find_free_time(args) {
+        const { timeMin, timeMax, duration } = schemas.toolInputs.findFreeTime.parse(args);
+        // Get existing events in the time range
+        const response = await calendar.events.list({
+            calendarId: 'primary',
+            timeMin,
+            timeMax,
+            singleEvents: true,
+            orderBy: 'startTime',
+        });
+        const events = response.data.items || [];
+        const freeTimes = [];
+        let currentTime = new Date(timeMin);
+        const endTime = new Date(timeMax);
+        const durationMs = duration * 60000; // Convert minutes to milliseconds
+        // Find free time slots
+        for (const event of events) {
+            const eventStart = new Date(event.start?.dateTime || event.start?.date || '');
+            // Check if there's enough time before the event
+            if (eventStart.getTime() - currentTime.getTime() >= durationMs) {
+                freeTimes.push({
+                    start: currentTime.toISOString(),
+                    end: new Date(eventStart.getTime() - 1).toISOString(),
+                });
+            }
+            currentTime = new Date(event.end?.dateTime || event.end?.date || '');
+        }
+        // Check for free time after the last event
+        if (endTime.getTime() - currentTime.getTime() >= durationMs) {
+            freeTimes.push({
+                start: currentTime.toISOString(),
+                end: endTime.toISOString(),
+            });
+        }
+        const formattedTimes = freeTimes.map(slot => `• ${new Date(slot.start).toLocaleString()} - ${new Date(slot.end).toLocaleString()}`).join('\n');
+        return {
+            content: [{
+                    type: "text",
+                    text: freeTimes.length ?
+                        `Found ${freeTimes.length} available time slots:\n\n${formattedTimes}` :
+                        `No available time slots found for duration of ${duration} minutes in the specified range.`
+                }]
+        };
+    },
+};
+// Initialize MCP server
+const server = new Server({
+    name: "google-calendar-server",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Register tool handlers
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    console.error("Tools requested by client");
+    return { tools: TOOL_DEFINITIONS };
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    console.error("Tools requested by client");
+    console.error("Returning tools:", JSON.stringify(TOOL_DEFINITIONS, null, 2));
+    return { tools: TOOL_DEFINITIONS };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        const handler = toolHandlers[name];
+        if (!handler) {
+            throw new Error(`Unknown tool: ${name}`);
+        }
+        return await handler(args);
+    }
+    catch (error) {
+        console.error(`Error executing tool ${name}:`, error);
+        throw error;
+    }
+});
+// Start the server
+async function main() {
+    try {
+        // Check for required environment variables (skip in test mode)
+        const isTestMode = process.env.MCP_TEST_MODE === 'true';
+        const requiredEnvVars = [
+            'GOOGLE_CLIENT_ID',
+            'GOOGLE_CLIENT_SECRET',
+            'GOOGLE_REDIRECT_URI',
+            'GOOGLE_REFRESH_TOKEN'
+        ];
+        const missingVars = requiredEnvVars.filter(varName => !process.env[varName]);
+        if (missingVars.length > 0 && !isTestMode) {
+            console.error(`Missing required environment variables: ${missingVars.join(', ')}`);
+            process.exit(1);
+        }
+        if (isTestMode) {
+            console.error("Running in test mode - skipping environment variable validation");
+        }
+        else {
+            console.error("Starting server with env vars:", {
+                clientId: process.env.GOOGLE_CLIENT_ID?.substring(0, 5) + '...',
+                clientSecret: process.env.GOOGLE_CLIENT_SECRET?.substring(0, 5) + '...',
+                redirectUri: process.env.GOOGLE_REDIRECT_URI,
+                hasRefreshToken: !!process.env.GOOGLE_REFRESH_TOKEN
+            });
+        }
+        const transport = new StdioServerTransport();
+        console.error("Created transport");
+        await server.connect(transport);
+        console.error("Connected to transport");
+        console.error("Google Calendar MCP Server running on stdio");
+    }
+    catch (error) {
+        console.error("Startup error:", error);
+        process.exit(1);
+    }
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@iflow-mcp/v-3-google-calendar",
+  "version": "1.0.0",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "iflow-mcp_v-3-google-calendar": "./build/index.js"
+  },
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "google-auth-library": "^9.15.0",
+    "googleapis": "^144.0.0",
+    "open": "^10.1.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  },
+  "files": [
+    "build"
+  ]
+}