ghub
Gmail, Drive, Sheets, Docs, and Calendar for AI agents, across several Google accounts, as an MCP server and a JSON CLI.
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
$ ghub call search_emails --json '{"account":"work","query":"is:unread","max_results":10}' \
--fields emails.id,emails.subject --limit 10
{"ok":true,"data":{"emails":[{"id":"...","subject":"..."}]},"meta":{"version":1}}
ghub is a local server that gives an AI assistant access to your Google accounts. It speaks the Model Context Protocol (MCP) over stdio or SSE, and the same 60 tools are also available as short CLI calls that print one JSON object. You sign in once per account with a built-in OAuth flow. After that, an agent can read and search across all your inboxes at once, or act on one account you name.
It is for people who run agents (Claude Code, Codex, Claude Desktop, or their own) and use more than one Google account. It exists because most Gmail MCP servers handle one account and need manual token setup.
account out. Write tools require an explicit account.begin_account_auth and finish_account_auth. Refreshed tokens are saved automatically.get_all_attachments extracts text from PDF, Word, and Excel files. Images are read with a small macOS Vision OCR helper when swiftc is available at install time.ghub tools, ghub schema TOOL, and ghub call TOOL give structured JSON, bounded output, validation-only --dry-run, and fixed exit codes. See docs/agent-cli.md.You need Node.js 20 or newer.
From a clone (the compiled dist/ is committed, so this works without a build step):
git clone https://github.com/tszaks/ghub.git
cd ghub
npm install
npm run build
node dist/index.js tools
Or from a release tarball (see docs/releases.md):
npm install -g ./ghub-1.7.0.tgz
ghub tools
npm install runs scripts/build-ocr.sh, which compiles the OCR helper only if swiftc is found (macOS). Without it, image attachments are saved to disk but no text is extracted.
ghub is not published to the npm registry.
begin_account_auth, open the URL it returns, then pass the code to finish_account_auth. Details are in OAuth onboarding.list_accounts to check that each account has a valid token.ghub runs as node /absolute/path/to/ghub/dist/index.js (or ghub mcp if installed from the tarball). With no arguments it starts the MCP server on stdio.
Claude Code
claude mcp add ghub -- node /absolute/path/to/ghub/dist/index.js
Codex (~/.codex/config.toml)
[mcp_servers.ghub]
command = "node"
args = ["/absolute/path/to/ghub/dist/index.js"]
Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"ghub": {
"command": "node",
"args": ["/absolute/path/to/ghub/dist/index.js"]
}
}
}
The server starts and lists its tools over stdio with no extra setup. Google calls begin only after you onboard an account.
To pass a variable to the server, add it to the client config, for example claude mcp add ghub -e GMAILMCPCONFIG_DIR=/custom/path -- node /absolute/path/to/ghub/dist/index.js.
Default configuration location: ~/.gmail-multi-mcp/
~/.gmail-multi-mcp/
├── accounts.json # Master account list
└── accounts/
├── personal/
│ ├── credentials.json # OAuth client credentials
│ ├── token.json # Access/refresh tokens
│ └── meta.json # Account metadata
└── work/
├── credentials.json
├── token.json
└── meta.json
{
"defaultAccount": "personal",
"accounts": [
{
"id": "personal",
"email": "[email protected]",
"displayName": "Personal Gmail",
"enabled": true,
"credentialPath": "~/.gmail-multi-mcp/accounts/personal/credentials.json",
"tokenPath": "~/.gmail-multi-mcp/accounts/personal/token.json"
},
{
"id": "work",
"email": "[email protected]",
"displayName": "Work Email",
"enabled": true,
"credentialPath": "~/.gmail-multi-mcp/accounts/work/credentials.json",
"tokenPath": "~/.gmail-multi-mcp/accounts/work/token.json"
}
]
}
Before using ghub, you need to set up a Google Cloud project:
https://mail.google.com/https://www.googleapis.com/auth/gmail.settings.basichttps://www.googleapis.com/auth/drivehttps://www.googleapis.com/auth/spreadsheetshttps://www.googleapis.com/auth/documentshttps://www.googleapis.com/auth/calendarThese scopes permit writes and are unchanged by the CLI. Human consent is required during the separate OAuth onboarding flow.
MCP_TRANSPORT=sse to force HTTP/SSE mode. If PORT is present, SSE mode starts automatically./sse and message posts go to /messages. GET / returns a plain text health line.npm start or node dist/index.js and let Railway provide PORT.The SSE server has no authentication of its own. Anyone who can reach the port can use every configured account. Run it only on a private network or behind your own access control.
Authenticate accounts directly through MCP tools:
Call the begin_account_auth tool with your OAuth credentials:
{
"account_id": "personal",
"email": "[email protected]",
"credentials_json": {
"installed": {
"client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
"client_secret": "YOUR_CLIENT_SECRET",
"redirect_uris": ["http://localhost"]
}
}
}
Or use a file path:
{
"account_id": "personal",
"email": "[email protected]",
"credentials_path": "/path/to/credentials.json"
}
The tool returns a Google OAuth URL. Open this URL in your browser.
code parameterCall finish_account_auth:
{
"account_id": "personal",
"authorization_code": "4/0AfJoh..."
}
Your account is now authenticated and ready to use.
// Aggregates across all enabled accounts
{
"max_results": 20,
"include_body": true
}
// Returns emails with source account indicated
{
"query": "from:[email protected] is:unread",
"max_results": 10
}
// Searches all enabled accounts, merges and sorts results
{
"account": "work",
"to": "[email protected]",
"subject": "Project Update",
"body": "Here's the latest on the project...",
"html": false
}
{
"account": "personal",
"max_results": 10,
"query": "label:important"
}
// Create a new label
{
"account": "personal",
"name": "Urgent-2026"
}
// Add label to messages
{
"account": "personal",
"message_ids": ["msg123", "msg456"],
"label_ids": ["Label_789"]
}
// Delete one or more drafts by their draft IDs (returned by create_draft)
{
"account": "personal",
"draft_ids": ["r5457071851533655344", "r774137312565667821"]
}
All 60 tools, taken from the live registry (ghub tools). Kind is read, write, or auth. Parameters for the first Gmail tools are in docs/api-reference.md. For the exact input schema of any tool, run ghub schema TOOL.
https://mail.google.com/), Gmail settings (filters), full Drive, Sheets, Docs, and Calendar. These allow reading and writing. ghub does not narrow them per tool.~/.gmail-multi-mcp by default). Protect that folder. credentials.json and token.json are git-ignored.send_email and create_draft read attachment paths you give them, upload_drive_file reads a local file, and attachment tools save files to disk.An agent can discover everything it needs at run time:
ghub tools # names, descriptions, read/write/auth kind
ghub schema search_emails # input schema, output envelope, example
ghub call send_email --dry-run --input - <<'JSON'
{"account":"work","to":"[email protected]","subject":"Example","body":"Hello"}
JSON
Use --dry-run to validate a write before running it. Mutations never pick a default account. See docs/agent-cli.md for the JSON contract and exit codes, and docs/agent-cli-spec.md for the specification.
This usually means your authorization code has expired. Authorization codes are single-use and expire after a few minutes.
Solution: Run begin_account_auth again to get a fresh OAuth URL and authorization code.
Your refresh token is no longer valid.
Solution:
token.json file for the affected accountbegin_account_auth then finish_account_auth)The OAuth token doesn't have the required scopes.
Solution:
The specified account ID doesn't exist in accounts.json.
Solution:
list_accounts to see available accountsenabled: true in accounts.jsonGmail API has rate limits (daily quota and per-user quotas).
Solution:
Read CONTRIBUTING.md. Report security problems as described in SECURITY.md. Everyone taking part follows the Code of Conduct. Agents working on the code should read AGENTS.md.
Docs: Agent CLI, CLI spec, API reference, Releases, Changelog.
Built by Tyler Szakacs.
MCP server and JSON CLI for Gmail, Drive, Sheets, Docs and Calendar across multiple Google accounts, with built-in OAuth.
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Ghub 透過 stdio 在本機執行。
上次檢查時間:2026-10-28。 MCP server and JSON CLI for Gmail, Drive, Sheets, Docs and Calendar across multiple Google accounts, with built-in OAuth.