AI 클라이언트가 로컬 저장소와 MCP server를 통해 Google Calendar 일정을 동기화, 검색 및 관리할 수 있게 합니다.
다른 이름 WireCatLabs/gcal-cli, gcal-cli, @wirecat/gcal-cli
- 스타
- 3
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- 0.28.0
- 마지막 커밋
- 2026년 11월 14일
- 라이선스
- Apache-2.0
WireCat Google Calendar MCP란?
AI 클라이언트가 로컬 저장소와 MCP server를 통해 Google Calendar 일정을 동기화, 검색 및 관리할 수 있게 합니다.
프로젝트 README에서 생성된 요약
WireCat Google Calendar MCP server 정보
WireCat Google Calendar를 사용하면 AI 에이전트가 로컬 저장소를 통해 Google Calendar 데이터와 상호작용할 수 있습니다. 캘린더를 컴퓨터로 동기화함으로써, 매번 읽기 작업을 수행할 때마다 네트워크 연결이 필요하지 않도록 에이전트의 일정 목록 조회, 검색 및 관리 기능을 지원합니다. 이 설정은 Claude Code 및 Gemini CLI와 같은 터미널 기반 에이전트나 Claude Desktop, Cursor와 같은 MCP 호환 클라이언트를 사용하는 개발자를 위해 설계되었습니다.
이 server를 사용하려면 직접 Google Cloud Console 데스크톱 앱을 생성하고 JSON client secret 파일을 제공해야 합니다. 사용자는 읽기 전용 액세스 또는 일정 생성, 이동, 삭제가 가능한 전체 쓰기 권한 중 하나를 선택할 수 있습니다. 시스템에는 일정을 삭제하기 전에 권한을 요청하거나, 명시적으로 허용하지 않는 한 참석자에게 자동으로 이메일을 보내는 것을 방지하는 등의 안전 기능이 포함되어 있습니다. 프로필 시스템을 통해 여러 Google 계정을 지원하며, 로컬 모델을 다운로드하면 시맨틱 검색도 수행할 수 있습니다.
활용 사례
- 1회의 가능 시간 확인특정 시간 범위 내에서 여러 명의 빈 시간대를 찾도록 에이전트에게 요청합니다.
- 2과거 일정 검색키워드나 의미를 사용하여 특정 과거 회의를 찾도록 에이전트에게 요청합니다.
- 3새 일정 예약새로운 캘린더 일정의 시간과 제목을 지정하여 예약하도록 에이전트에게 지시합니다.
- 4일정 충돌 확인동기화된 모든 계정을 스캔하여 겹치는 회의가 있는지 에이전트가 확인하도록 합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
WireCat Google Calendar MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 WireCat Google Calendar MCP 설치
$ claude mcp add gcal-cli -- npx -y @wirecat/gcal-cliCursor에 WireCat Google Calendar MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"gcal-cli": {
"command": "npx",
"args": [
"-y",
"@wirecat/gcal-cli"
]
}
}
}VS Code에 WireCat Google Calendar MCP 설치
.vscode/mcp.json
{
"servers": {
"gcal-cli": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@wirecat/gcal-cli"
]
}
}
}VS Code CLI에 WireCat Google Calendar MCP 설치
$ code --add-mcp '{"name":"gcal-cli","type":"stdio","command":"npx","args":["-y","@wirecat/gcal-cli"]}'Claude Desktop에 WireCat Google Calendar MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"gcal-cli": {
"command": "npx",
"args": [
"-y",
"@wirecat/gcal-cli"
]
}
}
}Codex에 WireCat Google Calendar MCP 설치
$ codex mcp add gcal-cli -- npx -y @wirecat/gcal-cliCodex config.toml에 WireCat Google Calendar MCP 설치
~/.codex/config.toml
[mcp_servers.gcal-cli] command = "npx" args = ["-y", "@wirecat/gcal-cli"]
Gemini CLI에 WireCat Google Calendar MCP 설치
$ gemini mcp add -s user gcal-cli npx -- -y @wirecat/gcal-cliGemini settings.json에 WireCat Google Calendar MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"gcal-cli": {
"command": "npx",
"args": [
"-y",
"@wirecat/gcal-cli"
]
}
}
}자동 검사
2026년 11월 14일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능wirecatlabs/gcal-cli is public and reachablegithub.com/wirecatlabs/gcal-cli ↗통과
- 패키지가 이 저장소를 소스로 명시@wirecat/gcal-cli names wirecatlabs/gcal-cli as sourcenpmjs.com/package/@wirecat/gcal-cli ↗통과
- 빌드 출처(Sigstore 증명)Sigstore attestation for @wirecat/gcal-clinpmjs.com/package/@wirecat/gcal-cli/v/0.26.0#provenance ↗통과
- 오픈 소스 라이선스 (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-14github.com/wirecatlabs/gcal-cli ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음No popular package one edit away from @wirecat/gcal-cli통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음the package checked; no critical advisoryosv.dev ↗통과
- 모델에 대한 숨겨진 지침 없음0 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기gcal — Google Calendar CLI for AI agents
gcal copies the calendars you own into the local WireCat store. Then you list, show and search
events, the people in them and their Drive files, with no network. With write access it also creates, changes, moves
and deletes events and answers invitations. A delete asks first. Mailing other people is off until you allow it.
An example conversation (invented people and events, illustrative output):
You: Use gcal. When can I meet Ana for 30 minutes this week?
Agent: (runs gcal personal calendars busy person:ana@example.com --duration-minutes 30)
You both are free on Tuesday 10:00–10:30, Wednesday 14:00–15:00 and Thursday 10:00–12:00.
You: Book Tuesday, 30 minutes, "Example planning". Do not email her.
Agent: Draft: "Example planning", Tuesday 10:00–10:30, with ana@example.com, no email sent. Create it?
You: Yes.
Quick start
You need a Google sign-in client of your own for now. Make one
in Google Cloud Console, as a Desktop app, and save its JSON file as ~/client_secret.json with chmod 600.
npm install -g @wirecat/gcal-cli
gcal skill install # the agent skill, for Claude Code, Codex and Gemini CLI
gcal personal session start --client-file ~/client_secret.json # sign in to Google in the browser, read-only
gcal personal sync # copy the calendars you own, then only what changed
gcal personal events list # your events from today on, earliest first
personal is a profile: a name you choose for one Google account. It is the first word of every command that uses an
account. A first sync lists a year back and three months ahead. A big one goes on over several runs: run sync again
when it says partial.
You need Node.js 22.16 or a later 22.x, or Node.js 24 or later, on macOS, Linux or Windows. Bun also works. Try it
without installing: npx @wirecat/gcal-cli --help. If gcal is not found, run gcal doctor. It needs no network and
shows what is set up. gcal guide gives step-by-step scenarios.
More: installation (wirecat.dev).
What you can do
See what is coming. "Use gcal. What is on my calendar this week?"
gcal personal events list
Find an event. "When did we plan the roadmap review?" Search runs on the local copy. It matches words, and meaning too once you download a model.
gcal personal search events roadmap planning
Find a time for everyone. Ask Google when people are busy, and get the stretches free for all of them. Nothing is stored.
gcal personal calendars busy person:ana@example.com --duration-minutes 30 --hours 10:00-16:00
More:
- Show one event with its attendees, Drive files and history:
gcal personal events show event:42. - Link a person to the same person in Telegram, WhatsApp or MAX:
gcal personal people link email:ana@example.com telegram:12345. - Create, change and delete events, repeating ones included, and answer invitations. Sign in again with
session start --grant writefirst. - Call any Google Calendar API v3 method by name with
gcal api.
More: use it (wirecat.dev).
For AI agents
Your agent. Your calendar. Your rules.
- An agent with a terminal — Claude Code, Codex, Gemini CLI, OpenClaw or Hermes Agent. It runs
gcalitself. The skill is the agent's instruction sheet: it explains the commands and the limits.gcal skill installwrites it. - An app with no terminal — Claude Desktop, Cursor and other MCP clients. Connect the profile's MCP server,
gcal personal mcp serve.gcal personal mcp configprints the entry to paste. - ChatGPT or Claude in a browser or on your phone — through your own HTTPS tunnel:
gcal personal mcp serve --http. Step by step (wirecat.dev).
gcal skill install # for Claude Code, Codex, Gemini CLI and OpenClaw
gcal personal mcp add claude-code --allow-writes # or: codex
gcal personal mcp check # start the server once, as the agent will
The server offers writing tools, so mcp add stops until you pass --allow-writes. The profile's permissions decide
what an agent may change; gcal personal config set permissions.api readonly keeps it to reads. Text from an invitation
is marked untrusted: it is data for the agent, never instructions. Commands that set up the sign-in or the agent link,
api call and emptying a calendar are never offered to an agent.
With --json, every command prints one JSON value, and an error comes as JSON with a code to branch on.
More: agents (wirecat.dev), settings and permissions (wirecat.dev).
Why this tool
- Your calendar is on your computer. It sits in the same store as the messages, documents and meetings of the other WireCat tools. An agent can answer "what did we agree with Ana" across all of them.
- Reads need no network after a sync. A meeting's passcode or PIN is never stored or printed.
- Every write is guarded. It never overwrites a change made in Google since the last sync. A delete asks first. It never mails attendees unless you allow it.
- Built for agents. A skill, an MCP server, one JSON form and exit codes a script can branch on.
Main features
- Incremental sync. After the first sync,
syncasks Google only for what changed.gcal personal store statusshows how far each calendar is. - Repeating events. Each occurrence is stored one by one, cancelled ones included.
- What changed.
events list changed_at>=2026-10-25lists the events that are new, moved or cancelled since a date. - All accounts in one list.
events list --source alllists the events of every Google account you signed in to, and says which accounts it read. - Meetings that overlap.
events list overlapping:true --source allfinds the meetings that clash, also across accounts. - Search by meaning.
gcal models download e5-smallfetches a small model once.sync --embedthen indexes new events with it. - Search in Google.
search events --backend serverasks Google's own search. It also finds events outside the synced span.--backend bothasks the store and Google together. - One search over everything.
search all roadmapfinds your meetings beside the chats that other WireCat tools stored and your notes, and says which accounts it read. - Every Google Calendar method.
gcal apireaches each one, under its own permission key.
Sign-in and profiles
Each profile is one Google account. No command ever picks a profile for you; gcal session list lists them.
gcal personal session start --client-file ~/client_secret.json # read-only
gcal personal session start --grant write # also create, change and delete events
gcal personal session start --grant write,sharing # also see and change who can see a calendar
gcal personal session status --check # ask Google whether the sign-in still works
GCAL_PROFILE=personal names the profile for a whole shell session. The sign-in is kept in the system keyring. Where
the keyring fails, gcal uses a private file and says so once. It never asks.
More: sign in (wirecat.dev).
Settings and permissions
Settings live in one config.json; gcal personal config show lists them. Permissions say what each command may do:
allow, ask, readonly or deny.
| Permission | What it covers | Default |
|---|---|---|
events.create, update, move, respond |
the event writes that are easy to undo | allow |
events.delete |
deleting an event | ask |
events.notify |
Google mails the other attendees | deny |
events.delete.series |
deleting every occurrence of a repeating event | deny |
sharing.notify |
Google mails the person a calendar is shared with | deny |
Sharing a calendar asks first. Over MCP nobody can answer a question, so ask lets a command run. An agent can then
share a calendar without asking you. To stop it, run gcal personal config set permissions.api.calendar.acl deny.
gcal personal config set permissions.api readonly # reads only, every method
gcal personal config set permissions.events.create ask # ask before each new event
gcal personal events create 3 --title 'Example planning' --start-time 2026-11-02T10:00 --end-time 2026-11-02T10:30 --dry-run
--dry-run shows the permission a command needs and does nothing. GCAL_READ_ONLY=1 refuses every write.
More: settings (wirecat.dev).
Limits
- Only the calendars you own sync at first.
gcal personal calendars listshows the rest, andgcal personal calendars sync 3adds calendar 3. gcalhas no Google app of its own yet. Sign-in needs your own client.- A Google app in Testing mode ends sign-ins after seven days. Sign in again, or publish the app.
calendars busyshows a person's busy times only when their calendar is shared with you or your organization.- Google's change notifications (
watch) are not offered: they need a public web address.
What is planned is on the roadmap (wirecat.dev).
Security
- Your event data goes only to Google. The sign-in is kept in the system keyring, or in a file only you can read.
- No command, error, log or run record shows a token or the client secret.
- A meeting's passcode or PIN is never stored. A join link is kept without its query string.
- A write never mails attendees, and a delete never runs unasked, unless you allow it.
gcalrefuses an OAuth client file that other users of the computer can read.- Permissions guard against an agent that a message talked into a change. They do not stop an agent that wants to get around them: for that, use a sandbox or a separate user.
More: security (wirecat.dev). Report a vulnerability as SECURITY.md says.
When it does not work
gcal doctor # what is set up; no network, no keyring
gcal personal session status --check # does Google still accept the sign-in
gcal personal sync --trace # the connection log, never content
gcal personal runs list # failed runs are kept
More: when something goes wrong (wirecat.dev).
Documentation
Each page is also on wirecat.dev/en/docs/gcal. Below are the sources in this repository.
| Section | Pages |
|---|---|
| Start | overview · installation · use it · ChatGPT or Claude in the browser |
| Reference | all commands · settings and permissions |
| If something is wrong | when something goes wrong · security |
| Project | roadmap · comparison with other tools |
| Changes | CHANGELOG.md |
For developers: design, tests and the rules for agents in AGENTS.md.
Development
pnpm install
pnpm lint && pnpm typecheck && pnpm test
pnpm build && pnpm smoke:node # the built command: the bundle users install
pnpm build && pnpm smoke:bun # the same under Bun
pnpm generate # rewrite the generated files
pnpm release:check # every check CI runs
The shared part — output streams, error codes, the keyring, the store, search and MCP — lives in
@wirecat/cli-base and its sibling library cli-core.
Part of WireCat
gcal is part of WireCat, an open-source, local-first context layer for AI agents. tg-cli and max-cli bring Telegram and MAX into the same local store. Start with one tool. Add more context when you need it. Your context. Any agent.
Questions and setup help: join the WireCat Discord. Bugs go to this repository's issues.
Contributing and license
Pull requests, bug reports and ideas go to issues.
Apache License 2.0 — LICENSE.
WireCat Google Calendar MCP 질문
WireCat Google Calendar MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add gcal-cli -- npx -y @wirecat/gcal-cli를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
WireCat Google Calendar MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
Claude Desktop 또는 Cursor에서 어떻게 사용하나요?
'gcal personal mcp serve' 명령어를 사용하여 프로필의 MCP server를 연결합니다.
일정을 검색할 때 에이전트에 인터넷 연결이 필요한가요?
아니요, 캘린더가 로컬 WireCat 저장소에 동기화되면 네트워크 연결 없이 로컬에서 검색을 수행합니다.
AI 에이전트가 회의 참석자에게 이메일을 보낼 수 있나요?
설정에서 명시적으로 허용하지 않는 한, 기본적으로 다른 사람에게 메일을 보내는 기능은 비활성화되어 있습니다.