google_calendar_mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: df0d244aad256eeb0562498694eae1a39552ad339bdf1af6db44fc5fcfb9df7d
+  data.tar.gz: d002407d26ed5f24bde23be4127e7d4e99dd5628d6513c4a46549a9b6fb5697d
+SHA512:
+  metadata.gz: 143687c3ec3f811f29bb3bc8290583f3719a7740b3a5f2fbdb7c5f5461a639463871e912d9f2498a2dd594e670b89eea495a195c2e300a53bc06e1c5e06e9b63
+  data.tar.gz: bde95ec1b73edc50566d4da382eb6455398dc9903c00f9a8ac4ff4f25b6e829f82075fb31f32fc3573e1dadec8de91e60447d9a74c26cd31046ae046d18eae1c

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mari Imaizumi
+
+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.

data/README.md

@@ -0,0 +1,88 @@
+# google_calendar_mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for Google Calendar, written in Ruby.
+
+It exposes the following tools to MCP clients:
+
+- `list_calendars` — list calendars accessible by the authenticated user
+- `list_events` — list events from a calendar (supports time range, free-text search, max results)
+- `get_event` — fetch detailed information about a specific event
+
+The server requires only **read-only** access to your calendars (`AUTH_CALENDAR_READONLY`).
+
+## Installation
+
+```sh
+gem install google_calendar_mcp
+```
+
+Or add it to a Gemfile:
+
+```ruby
+gem "google_calendar_mcp"
+```
+
+## Setup
+
+### 1. Create OAuth credentials
+
+1. Open the [Google Cloud Console](https://console.cloud.google.com/) and create (or select) a project.
+2. Enable the **Google Calendar API**.
+3. Create an OAuth 2.0 Client ID of type **Desktop app**.
+4. Download the JSON file and save it as `credentials.json`.
+
+### 2. Authorize the server
+
+Run the server once from a working directory containing `credentials.json`:
+
+```sh
+google-calendar-mcp-server
+```
+
+On first run it prints an authorization URL. Open it in your browser, grant access, paste the code back in, and the server stores a refresh token in `token.yaml`.
+
+### 3. Configure your MCP client
+
+Example for Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "google-calendar": {
+      "command": "google-calendar-mcp-server",
+      "env": {
+        "GOOGLE_CREDENTIALS_PATH": "/absolute/path/to/credentials.json",
+        "GOOGLE_TOKEN_PATH": "/absolute/path/to/token.yaml"
+      }
+    }
+  }
+}
+```
+
+### Environment variables
+
+| Variable                   | Purpose                                                                |
+| -------------------------- | ---------------------------------------------------------------------- |
+| `GOOGLE_CREDENTIALS_PATH`  | Path to the OAuth client JSON file. Default: `credentials.json`.       |
+| `GOOGLE_TOKEN_PATH`        | Path to the stored refresh token YAML. Default: `token.yaml`.          |
+| `GOOGLE_CREDENTIALS_JSON`  | Raw OAuth client JSON. Overrides the file path when set.               |
+| `GOOGLE_TOKEN_YAML`        | Raw token YAML. Overrides the file path when set.                      |
+
+The `*_JSON` / `*_YAML` variables are convenient when running in environments where writing files is awkward (e.g. inside another process's config).
+
+## Development
+
+```sh
+bundle install
+bundle exec ruby -Ilib exe/google-calendar-mcp-server
+```
+
+To build the gem locally:
+
+```sh
+gem build google_calendar_mcp.gemspec
+```
+
+## License
+
+[MIT](LICENSE)

data/exe/google-calendar-mcp-server

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "google_calendar_mcp"
+
+GoogleCalendarMcp::Server.start

data/google_calendar_mcp.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "lib/google_calendar_mcp/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "google_calendar_mcp"
+  spec.version = GoogleCalendarMcp::VERSION
+  spec.authors = ["Mari Imaizumi"]
+  spec.email = ["mariimaizumi5@gmail.com"]
+
+  spec.summary = "A Model Context Protocol (MCP) server for Google Calendar"
+  spec.description = "Provides MCP tools to list calendars, list events, and fetch event details from Google Calendar."
+  spec.homepage = "https://github.com/ima1zumi/google-calendar-mcp-server"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "exe/*",
+    "LICENSE",
+    "README.md",
+    "google_calendar_mcp.gemspec"
+  ]
+  spec.bindir = "exe"
+  spec.executables = ["google-calendar-mcp-server"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "mcp", "~> 0.8"
+  spec.add_dependency "google-apis-calendar_v3", "~> 0.52"
+  spec.add_dependency "googleauth", "~> 1.14"
+end

data/lib/google_calendar_mcp/auth.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "google/apis/calendar_v3"
+require "googleauth"
+require "googleauth/stores/file_token_store"
+require "json"
+require "yaml"
+
+module GoogleCalendarMcp
+  module Auth
+    SCOPE = Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY
+
+    module_function
+
+    def build_service
+      service = Google::Apis::CalendarV3::CalendarService.new
+      service.client_options.application_name = "Google Calendar MCP Server"
+      service.authorization = authorize
+      service
+    end
+
+    def authorize
+      credentials_json = ENV.fetch("GOOGLE_CREDENTIALS_JSON", nil)
+      token_yaml = ENV.fetch("GOOGLE_TOKEN_YAML", nil)
+
+      if credentials_json && !credentials_json.empty? && token_yaml && !token_yaml.empty?
+        authorize_from_env(credentials_json, token_yaml)
+      else
+        authorize_from_file
+      end
+    end
+
+    def authorize_from_env(credentials_json, token_yaml)
+      parsed = JSON.parse(credentials_json)
+      installed = parsed.fetch("installed") { parsed.fetch("web") }
+
+      token_data = YAML.safe_load(token_yaml)
+      token_json = JSON.parse(token_data.fetch("default") { token_data.values.first })
+
+      Google::Auth::UserRefreshCredentials.new(
+        client_id: installed.fetch("client_id"),
+        client_secret: installed.fetch("client_secret"),
+        scope: SCOPE,
+        refresh_token: token_json.fetch("refresh_token")
+      )
+    end
+
+    def authorize_from_file
+      credentials_path = ENV.fetch("GOOGLE_CREDENTIALS_PATH", "credentials.json")
+      token_path = ENV.fetch("GOOGLE_TOKEN_PATH", "token.yaml")
+
+      client_id = Google::Auth::ClientId.from_file(credentials_path)
+      token_store = Google::Auth::Stores::FileTokenStore.new(file: token_path)
+      authorizer = Google::Auth::UserAuthorizer.new(client_id, SCOPE, token_store)
+
+      user_id = "default"
+      credentials = authorizer.get_credentials(user_id)
+
+      if credentials.nil?
+        url = authorizer.get_authorization_url(base_url: "http://localhost:8080")
+        $stderr.puts "Open this URL in your browser to authorize:"
+        $stderr.puts url
+        $stderr.puts "Enter the authorization code:"
+        code = $stdin.gets&.strip
+        credentials = authorizer.get_and_store_credentials_from_code(
+          user_id: user_id,
+          code: code,
+          base_url: "http://localhost:8080"
+        )
+      end
+
+      credentials
+    end
+  end
+end

data/lib/google_calendar_mcp/server.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "mcp"
+require_relative "tools/list_calendars"
+require_relative "tools/list_events"
+require_relative "tools/get_event"
+
+module GoogleCalendarMcp
+  module Server
+    module_function
+
+    def start
+      server = MCP::Server.new(
+        name: "google-calendar",
+        tools: [
+          GoogleCalendarMcp::Tools::ListCalendars,
+          GoogleCalendarMcp::Tools::ListEvents,
+          GoogleCalendarMcp::Tools::GetEvent
+        ]
+      )
+
+      transport = MCP::Server::Transports::StdioTransport.new(server)
+      transport.open
+    end
+  end
+end

data/lib/google_calendar_mcp/tools/get_event.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "mcp"
+require "json"
+require_relative "../auth"
+
+module GoogleCalendarMcp
+  module Tools
+    class GetEvent < MCP::Tool
+      description "Get detailed information about a specific calendar event"
+
+      input_schema(
+        properties: {
+          calendar_id: {
+            type: "string",
+            description: "Calendar ID containing the event. Defaults to 'primary'."
+          },
+          event_id: {
+            type: "string",
+            description: "The unique identifier of the event to retrieve."
+          }
+        },
+        required: ["event_id"]
+      )
+
+      class << self
+        def call(event_id:, calendar_id: "primary", server_context:)
+          service = GoogleCalendarMcp::Auth.build_service
+          event = service.get_event(calendar_id, event_id)
+
+          attendees = event.attendees&.map do |a|
+            { email: a.email, response_status: a.response_status, display_name: a.display_name }
+          end
+
+          result = {
+            id: event.id,
+            summary: event.summary,
+            description: event.description,
+            start: event.start&.date_time&.to_s || event.start&.date,
+            end: event.end&.date_time&.to_s || event.end&.date,
+            location: event.location,
+            status: event.status,
+            creator: event.creator&.email,
+            organizer: event.organizer&.email,
+            attendees: attendees,
+            hangout_link: event.hangout_link,
+            html_link: event.html_link,
+            created: event.created&.to_s,
+            updated: event.updated&.to_s
+          }
+
+          MCP::Tool::Response.new([
+            { type: "text", text: JSON.pretty_generate(result) }
+          ])
+        end
+      end
+    end
+  end
+end

data/lib/google_calendar_mcp/tools/list_calendars.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "mcp"
+require "json"
+require_relative "../auth"
+
+module GoogleCalendarMcp
+  module Tools
+    class ListCalendars < MCP::Tool
+      description "List all calendars accessible by the authenticated user"
+
+      input_schema(
+        properties: {}
+      )
+
+      class << self
+        def call(server_context:)
+          service = GoogleCalendarMcp::Auth.build_service
+          response = service.list_calendar_lists
+
+          calendars = response.items.map do |calendar|
+            {
+              id: calendar.id,
+              summary: calendar.summary,
+              primary: calendar.primary || false,
+              access_role: calendar.access_role
+            }
+          end
+
+          MCP::Tool::Response.new([
+            { type: "text", text: JSON.pretty_generate(calendars) }
+          ])
+        end
+      end
+    end
+  end
+end

data/lib/google_calendar_mcp/tools/list_events.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "mcp"
+require "json"
+require "time"
+require_relative "../auth"
+
+module GoogleCalendarMcp
+  module Tools
+    class ListEvents < MCP::Tool
+      description "List events from a Google Calendar. Returns upcoming events by default."
+
+      input_schema(
+        properties: {
+          calendar_id: {
+            type: "string",
+            description: "Calendar ID to list events from. Defaults to 'primary'."
+          },
+          time_min: {
+            type: "string",
+            description: "Lower bound (inclusive) for event start time, in ISO 8601 format (e.g. '2025-01-01T00:00:00Z'). Defaults to current time."
+          },
+          time_max: {
+            type: "string",
+            description: "Upper bound (exclusive) for event end time, in ISO 8601 format."
+          },
+          max_results: {
+            type: "integer",
+            description: "Maximum number of events to return (1-2500). Defaults to 25."
+          },
+          query: {
+            type: "string",
+            description: "Free text search terms to find events that match."
+          }
+        }
+      )
+
+      class << self
+        def call(calendar_id: "primary", time_min: nil, time_max: nil, max_results: 25, query: nil, server_context:)
+          service = GoogleCalendarMcp::Auth.build_service
+
+          params = {
+            single_events: true,
+            order_by: "startTime",
+            max_results: max_results,
+            time_min: time_min || Time.now.iso8601
+          }
+          params[:time_max] = time_max if time_max
+          params[:q] = query if query
+
+          response = service.list_events(calendar_id, **params)
+
+          events = (response.items || []).map do |event|
+            {
+              id: event.id,
+              summary: event.summary,
+              start: event.start&.date_time&.to_s || event.start&.date,
+              end: event.end&.date_time&.to_s || event.end&.date,
+              location: event.location
+            }
+          end
+
+          MCP::Tool::Response.new([
+            { type: "text", text: JSON.pretty_generate(events) }
+          ])
+        end
+      end
+    end
+  end
+end

data/lib/google_calendar_mcp/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GoogleCalendarMcp
+  VERSION = "0.1.0"
+end

data/lib/google_calendar_mcp.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "google_calendar_mcp/version"
+require_relative "google_calendar_mcp/auth"
+require_relative "google_calendar_mcp/server"
+
+module GoogleCalendarMcp
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: google_calendar_mcp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mari Imaizumi
+bindir: exe
+cert_chain: []
+date: 2026-06-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: google-apis-calendar_v3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.52'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.52'
+- !ruby/object:Gem::Dependency
+  name: googleauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+description: Provides MCP tools to list calendars, list events, and fetch event details
+  from Google Calendar.
+email:
+- mariimaizumi5@gmail.com
+executables:
+- google-calendar-mcp-server
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/google-calendar-mcp-server
+- google_calendar_mcp.gemspec
+- lib/google_calendar_mcp.rb
+- lib/google_calendar_mcp/auth.rb
+- lib/google_calendar_mcp/server.rb
+- lib/google_calendar_mcp/tools/get_event.rb
+- lib/google_calendar_mcp/tools/list_calendars.rb
+- lib/google_calendar_mcp/tools/list_events.rb
+- lib/google_calendar_mcp/version.rb
+homepage: https://github.com/ima1zumi/google-calendar-mcp-server
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ima1zumi/google-calendar-mcp-server
+  bug_tracker_uri: https://github.com/ima1zumi/google-calendar-mcp-server/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: A Model Context Protocol (MCP) server for Google Calendar
+test_files: []