@shivaduke28/gmail-mcp 0.1.0

package/README.md

@@ -0,0 +1,109 @@
+# gmail-mcp
+
+Gmail API の MCP (Model Context Protocol) サーバー。
+
+OAuth スコープは `gmail.modify` のみ。送信・削除はできません。
+
+## Tools
+
+| ツール | 説明 |
+|---|---|
+| `search-messages` | Gmail 検索クエリでメール一覧を取得する（TOON形式） |
+| `get-messages` | メッセージIDから本文を含む詳細を一括取得する |
+| `get-threads` | スレッドIDからスレッド全体を一括取得する |
+| `create-draft` | 下書きを作成する（返信にも対応） |
+| `modify-labels` | ラベルの追加・削除（アーカイブ = INBOX 削除） |
+| `list-labels` | 利用可能なラベル一覧を取得する |
+
+レスポンスは [TOON](https://github.com/toon-format/toon) 形式で返されます。
+
+## Setup
+
+### 1. GCP プロジェクトの準備
+
+1. [Google Cloud Console](https://console.cloud.google.com/) でプロジェクトを作成
+2. Gmail API を有効化
+3. OAuth 同意画面を設定
+4. OAuth 2.0 クライアント ID を作成（デスクトップアプリ）
+5. 認証情報の JSON ファイルをダウンロード → `credentials.json` として保存
+
+### 2. 使い方
+
+#### npx（推奨）
+
+```json
+{
+  "mcpServers": {
+    "gmail": {
+      "command": "npx",
+      "args": ["-y", "@shivaduke28/gmail-mcp"],
+      "env": {
+        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/credentials.json",
+        "GOOGLE_OAUTH_TOKENS": "/path/to/tokens.json"
+      }
+    }
+  }
+}
+```
+
+#### ソースから実行
+
+```bash
+npm install
+npm run build
+```
+
+```json
+{
+  "mcpServers": {
+    "gmail": {
+      "command": "node",
+      "args": ["/path/to/gmail-mcp/dist/index.js"],
+      "env": {
+        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/credentials.json",
+        "GOOGLE_OAUTH_TOKENS": "/path/to/tokens.json"
+      }
+    }
+  }
+}
+```
+
+### 3. 環境変数
+
+| 変数 | 必須 | 説明 |
+|---|---|---|
+| `GOOGLE_OAUTH_CREDENTIALS` | Yes | OAuth クライアント認証情報の JSON ファイルパス |
+| `GOOGLE_OAUTH_TOKENS` | Yes | ユーザートークンの保存先パス。初回認証時に自動生成 |
+
+### 4. 認証
+
+初回起動時にブラウザが開き、Google アカウントでの認証を求められます。認証後、トークンが `GOOGLE_OAUTH_TOKENS` で指定したパスに自動保存され、以降はブラウザ認証なしで起動できます。
+
+## Gmail 検索クエリの例
+
+```
+from:user@example.com
+to:user@example.com
+subject:会議
+is:unread
+has:attachment
+newer_than:7d
+after:2026/01/01
+label:INBOX
+```
+
+組み合わせも可能: `from:example.com subject:請求書 after:2026/01/01`
+
+## Development
+
+```bash
+npm install
+npm run dev          # tsx で開発実行
+npm run build        # tsc でビルド
+npm run test         # テスト実行
+npm run typecheck    # 型チェック
+```
+
+## License
+
+ISC

package/dist/auth.js

@@ -0,0 +1,70 @@
+import { OAuth2Client } from "google-auth-library";
+import { readFile, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { exec } from "node:child_process";
+const SCOPES = [
+    "https://www.googleapis.com/auth/gmail.modify",
+];
+export async function authorize(credentialsPath, tokensPath) {
+    const content = await readFile(credentialsPath, "utf-8");
+    const credentials = JSON.parse(content);
+    const { client_id, client_secret } = credentials.installed;
+    const oauth2Client = new OAuth2Client(client_id, client_secret, "http://localhost:3000/callback");
+    // 保存済みトークンがあれば読み込む
+    try {
+        const tokens = JSON.parse(await readFile(tokensPath, "utf-8"));
+        oauth2Client.setCredentials(tokens);
+        return oauth2Client;
+    }
+    catch {
+        // トークンがなければブラウザ認証
+    }
+    const tokens = await authenticateWithBrowser(oauth2Client);
+    await writeFile(tokensPath, JSON.stringify(tokens, null, 2));
+    oauth2Client.setCredentials(tokens);
+    return oauth2Client;
+}
+function authenticateWithBrowser(oauth2Client) {
+    return new Promise((resolve, reject) => {
+        const authUrl = oauth2Client.generateAuthUrl({
+            access_type: "offline",
+            scope: SCOPES,
+        });
+        const server = createServer(async (req, res) => {
+            if (!req.url?.startsWith("/callback"))
+                return;
+            const url = new URL(req.url, "http://localhost:3000");
+            const code = url.searchParams.get("code");
+            if (!code) {
+                res.writeHead(400);
+                res.end("No code received");
+                reject(new Error("No authorization code received"));
+                server.close();
+                return;
+            }
+            try {
+                const { tokens } = await oauth2Client.getToken(code);
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end("<h1>認証成功！このタブを閉じてください。</h1>");
+                resolve(tokens);
+            }
+            catch (err) {
+                res.writeHead(500);
+                res.end("Token exchange failed");
+                reject(err);
+            }
+            finally {
+                server.close();
+            }
+        });
+        server.listen(3000, () => {
+            console.error(`\n認証が必要です。ブラウザを開きます...\n`);
+            const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+            exec(`${command} '${authUrl}'`, (err) => {
+                if (err) {
+                    console.error(`ブラウザの自動起動に失敗しました。以下のURLを手動で開いてください:\n${authUrl}\n`);
+                }
+            });
+        });
+    });
+}

package/dist/gmail.js

@@ -0,0 +1,67 @@
+export function extractHeaders(headers) {
+    const get = (name) => {
+        return headers?.find((h) => h.name?.toLowerCase() === name.toLowerCase())?.value ?? "";
+    };
+    return {
+        from: get("From"),
+        to: get("To"),
+        cc: get("Cc"),
+        subject: get("Subject"),
+        date: get("Date"),
+    };
+}
+export function extractBody(payload) {
+    if (!payload)
+        return "";
+    // text/plain を直接持っている場合
+    if (payload.mimeType === "text/plain" && payload.body?.data) {
+        return decodeBase64Url(payload.body.data);
+    }
+    // multipart の場合は再帰的にパース
+    if (payload.parts) {
+        // まず text/plain を探す
+        for (const part of payload.parts) {
+            if (part.mimeType === "text/plain" && part.body?.data) {
+                return decodeBase64Url(part.body.data);
+            }
+        }
+        // text/plain がなければ再帰的に探す
+        for (const part of payload.parts) {
+            const body = extractBody(part);
+            if (body)
+                return body;
+        }
+    }
+    return "";
+}
+function decodeBase64Url(data) {
+    const base64 = data.replace(/-/g, "+").replace(/_/g, "/");
+    return Buffer.from(base64, "base64").toString("utf-8");
+}
+function encodeBase64Url(data) {
+    return Buffer.from(data, "utf-8")
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+export function buildRawMessage(to, cc, subject, body, threadId, inReplyTo, references) {
+    const lines = [];
+    lines.push(`To: ${to.join(", ")}`);
+    if (cc.length > 0) {
+        lines.push(`Cc: ${cc.join(", ")}`);
+    }
+    lines.push(`Subject: =?UTF-8?B?${Buffer.from(subject).toString("base64")}?=`);
+    lines.push("MIME-Version: 1.0");
+    lines.push("Content-Type: text/plain; charset=UTF-8");
+    lines.push("Content-Transfer-Encoding: base64");
+    if (inReplyTo) {
+        lines.push(`In-Reply-To: ${inReplyTo}`);
+    }
+    if (references) {
+        lines.push(`References: ${references}`);
+    }
+    lines.push("");
+    lines.push(Buffer.from(body).toString("base64"));
+    return encodeBase64Url(lines.join("\r\n"));
+}

package/dist/index.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { encode } from "@toon-format/toon";
+import { authorize } from "./auth.js";
+import { gmail as googleGmail } from "@googleapis/gmail";
+import { extractHeaders, extractBody, buildRawMessage } from "./gmail.js";
+import { existsSync } from "node:fs";
+const credentialsPath = process.env.GOOGLE_OAUTH_CREDENTIALS;
+const tokensPath = process.env.GOOGLE_OAUTH_TOKENS;
+if (!credentialsPath) {
+    console.error("GOOGLE_OAUTH_CREDENTIALS 環境変数を設定してください");
+    process.exit(1);
+}
+if (!tokensPath) {
+    console.error("GOOGLE_OAUTH_TOKENS 環境変数を設定してください");
+    process.exit(1);
+}
+if (!existsSync(credentialsPath)) {
+    console.error(`credentials.json が見つかりません: ${credentialsPath}`);
+    process.exit(1);
+}
+// OAuth2認証
+const auth = await authorize(credentialsPath, tokensPath);
+const gmail = googleGmail({ version: "v1", auth });
+const server = new McpServer({
+    name: "gmail-mcp",
+    version: "0.1.0",
+});
+// 1. search-messages
+server.registerTool("search-messages", {
+    description: "Gmail検索クエリでメール一覧を取得する。レスポンスはTOON形式で返す。",
+    inputSchema: {
+        query: z.string().describe("Gmail検索クエリ（例: from:user@example.com, subject:会議, is:unread など）"),
+        maxResults: z.number().optional().default(20).describe("最大取得件数"),
+    },
+}, async ({ query, maxResults }) => {
+    const res = await gmail.users.messages.list({
+        userId: "me",
+        q: query,
+        maxResults,
+    });
+    const messageIds = res.data.messages ?? [];
+    if (messageIds.length === 0) {
+        return {
+            content: [{ type: "text", text: "メッセージが見つかりませんでした" }],
+        };
+    }
+    const details = await Promise.all(messageIds
+        .filter((msg) => msg.id)
+        .map((msg) => gmail.users.messages.get({
+        userId: "me",
+        id: msg.id,
+        format: "metadata",
+        metadataHeaders: ["From", "To", "Cc", "Subject", "Date"],
+    })));
+    const rows = details.map((detail) => {
+        const headers = extractHeaders(detail.data.payload?.headers);
+        return {
+            date: headers.date,
+            from: headers.from,
+            to: headers.to,
+            cc: headers.cc,
+            subject: headers.subject,
+            snippet: detail.data.snippet ?? "",
+            id: detail.data.id ?? "",
+            threadId: detail.data.threadId ?? "",
+            labels: (detail.data.labelIds ?? []).join(", "),
+        };
+    });
+    return {
+        content: [{
+                type: "text",
+                text: encode({ messages: rows }),
+            }],
+    };
+});
+// 2. get-messages
+server.registerTool("get-messages", {
+    description: "複数のメッセージIDで本文を含むメール詳細を一括取得する。",
+    inputSchema: {
+        messageIds: z.array(z.string()).describe("メッセージIDの配列"),
+    },
+}, async ({ messageIds }) => {
+    const details = await Promise.all(messageIds.map((id) => gmail.users.messages.get({
+        userId: "me",
+        id,
+        format: "full",
+    })));
+    const messages = details.map((detail) => {
+        const headers = extractHeaders(detail.data.payload?.headers);
+        const body = extractBody(detail.data.payload ?? undefined);
+        return {
+            id: detail.data.id ?? "",
+            threadId: detail.data.threadId ?? "",
+            labels: (detail.data.labelIds ?? []).join(", "),
+            date: headers.date,
+            from: headers.from,
+            to: headers.to,
+            cc: headers.cc,
+            subject: headers.subject,
+            body,
+        };
+    });
+    return {
+        content: [{
+                type: "text",
+                text: encode({ messages }),
+            }],
+    };
+});
+// 3. get-threads
+server.registerTool("get-threads", {
+    description: "複数のスレッドIDでスレッド全体のメッセージを一括取得する。",
+    inputSchema: {
+        threadIds: z.array(z.string()).describe("スレッドIDの配列"),
+    },
+}, async ({ threadIds }) => {
+    const threads = await Promise.all(threadIds.map((id) => gmail.users.threads.get({
+        userId: "me",
+        id,
+        format: "full",
+    })));
+    const result = threads.map((thread) => {
+        const messages = (thread.data.messages ?? []).map((msg) => {
+            const headers = extractHeaders(msg.payload?.headers);
+            const body = extractBody(msg.payload ?? undefined);
+            return {
+                id: msg.id ?? "",
+                date: headers.date,
+                from: headers.from,
+                to: headers.to,
+                cc: headers.cc,
+                subject: headers.subject,
+                labels: (msg.labelIds ?? []).join(", "),
+                body,
+            };
+        });
+        return {
+            threadId: thread.data.id ?? "",
+            messages,
+        };
+    });
+    return {
+        content: [{
+                type: "text",
+                text: encode({ threads: result }),
+            }],
+    };
+});
+// 4. create-draft
+server.registerTool("create-draft", {
+    description: "メールの下書きを作成する。返信の場合はthreadIdとinReplyToMessageIdを指定する。",
+    inputSchema: {
+        to: z.array(z.string()).describe("宛先メールアドレスの配列"),
+        cc: z.array(z.string()).optional().default([]).describe("CCメールアドレスの配列"),
+        subject: z.string().describe("件名"),
+        body: z.string().describe("本文"),
+        threadId: z.string().optional().describe("返信先スレッドID（返信時に指定）"),
+        inReplyToMessageId: z.string().optional().describe("返信先メッセージID（返信時に指定。Referencesヘッダー構築用）"),
+    },
+}, async ({ to, cc, subject, body, threadId, inReplyToMessageId }) => {
+    // 返信時のヘッダー構築
+    let inReplyTo;
+    let references;
+    if (inReplyToMessageId && threadId) {
+        try {
+            const origMsg = await gmail.users.messages.get({
+                userId: "me",
+                id: inReplyToMessageId,
+                format: "metadata",
+                metadataHeaders: ["Message-ID", "References"],
+            });
+            const origHeaders = origMsg.data.payload?.headers ?? [];
+            const messageIdHeader = origHeaders.find((h) => h.name?.toLowerCase() === "message-id")?.value ?? "";
+            const referencesHeader = origHeaders.find((h) => h.name?.toLowerCase() === "references")?.value ?? "";
+            if (messageIdHeader) {
+                inReplyTo = messageIdHeader;
+                references = referencesHeader ? `${referencesHeader} ${messageIdHeader}` : messageIdHeader;
+            }
+        }
+        catch {
+            // 元メッセージの取得に失敗しても下書き作成は続行
+        }
+    }
+    const raw = buildRawMessage(to, cc, subject, body, threadId, inReplyTo, references);
+    const draft = await gmail.users.drafts.create({
+        userId: "me",
+        requestBody: {
+            message: {
+                raw,
+                ...(threadId && { threadId }),
+            },
+        },
+    });
+    return {
+        content: [{
+                type: "text",
+                text: `下書きを作成しました (ID: ${draft.data.id})`,
+            }],
+    };
+});
+// 5. modify-labels
+server.registerTool("modify-labels", {
+    description: "メッセージのラベルを追加/削除する。アーカイブはremoveLabelIdsに\"INBOX\"を指定する。",
+    inputSchema: {
+        messageIds: z.array(z.string()).describe("メッセージIDの配列"),
+        addLabelIds: z.array(z.string()).optional().default([]).describe("追加するラベルIDの配列"),
+        removeLabelIds: z.array(z.string()).optional().default([]).describe("削除するラベルIDの配列"),
+    },
+}, async ({ messageIds, addLabelIds, removeLabelIds }) => {
+    await gmail.users.messages.batchModify({
+        userId: "me",
+        requestBody: {
+            ids: messageIds,
+            addLabelIds,
+            removeLabelIds,
+        },
+    });
+    return {
+        content: [{
+                type: "text",
+                text: `${messageIds.length}件のメッセージのラベルを更新しました。`,
+            }],
+    };
+});
+// 6. list-labels
+server.registerTool("list-labels", {
+    description: "利用可能なラベル一覧を取得する。レスポンスはTOON形式で返す。",
+    inputSchema: {},
+}, async () => {
+    const res = await gmail.users.labels.list({ userId: "me" });
+    const labels = (res.data.labels ?? []).map((label) => ({
+        id: label.id ?? "",
+        name: label.name ?? "",
+        type: label.type ?? "",
+    }));
+    return {
+        content: [{
+                type: "text",
+                text: encode({ labels }),
+            }],
+    };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/permissions.js

@@ -0,0 +1,94 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+export const PermissionAction = {
+    Allow: "allow",
+    Deny: "deny",
+};
+export const OperationType = {
+    Read: "read",
+    CreateDraft: "create_draft",
+    ModifyLabels: "modify_labels",
+};
+const DEFAULT_CONFIG = {
+    internalDomain: "",
+    permissions: {
+        read: {
+            self_only: PermissionAction.Allow,
+            internal: PermissionAction.Allow,
+            external: PermissionAction.Allow,
+        },
+        create_draft: {
+            self_only: PermissionAction.Allow,
+            internal: PermissionAction.Allow,
+            external: PermissionAction.Deny,
+        },
+        modify_labels: {
+            self_only: PermissionAction.Allow,
+            internal: PermissionAction.Allow,
+            external: PermissionAction.Allow,
+        },
+    },
+};
+export async function loadPermissionConfig(configPath) {
+    if (!configPath)
+        return DEFAULT_CONFIG;
+    // ファイルがなければデフォルト設定を書き出す
+    if (!existsSync(configPath)) {
+        try {
+            await writeFile(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n");
+            console.error(`permissions.json を作成しました: ${configPath}`);
+        }
+        catch {
+            console.error(`permissions.json の作成に失敗しました: ${configPath}`);
+        }
+        return DEFAULT_CONFIG;
+    }
+    try {
+        const content = await readFile(configPath, "utf-8");
+        const parsed = JSON.parse(content);
+        return {
+            internalDomain: parsed.internalDomain ?? DEFAULT_CONFIG.internalDomain,
+            permissions: {
+                read: parsed.permissions?.read ?? DEFAULT_CONFIG.permissions.read,
+                create_draft: parsed.permissions?.create_draft ?? DEFAULT_CONFIG.permissions.create_draft,
+                modify_labels: parsed.permissions?.modify_labels ?? DEFAULT_CONFIG.permissions.modify_labels,
+            },
+        };
+    }
+    catch {
+        console.error(`設定ファイルの読み込みに失敗しました: ${configPath}`);
+        return DEFAULT_CONFIG;
+    }
+}
+export const RecipientCondition = {
+    SelfOnly: "self_only",
+    Internal: "internal",
+    External: "external",
+};
+export function classifyRecipients(recipients, selfEmail, internalDomain) {
+    const others = recipients.filter((email) => email.toLowerCase() !== selfEmail.toLowerCase());
+    if (others.length === 0)
+        return RecipientCondition.SelfOnly;
+    if (internalDomain && others.every((email) => email.toLowerCase().endsWith(`@${internalDomain.toLowerCase()}`))) {
+        return RecipientCondition.Internal;
+    }
+    return RecipientCondition.External;
+}
+export function checkPermission(config, operation, recipients, selfEmail) {
+    const perm = config.permissions[operation];
+    const condition = classifyRecipients(recipients, selfEmail, config.internalDomain);
+    return { action: perm[condition], condition };
+}
+const CONDITION_LABELS = {
+    [RecipientCondition.SelfOnly]: "自分のみ",
+    [RecipientCondition.Internal]: "内部メンバー",
+    [RecipientCondition.External]: "外部宛先",
+};
+const OPERATION_LABELS = {
+    [OperationType.Read]: "読み取り",
+    [OperationType.CreateDraft]: "下書き作成",
+    [OperationType.ModifyLabels]: "ラベル変更",
+};
+export function denyMessage(operation, condition) {
+    return `${CONDITION_LABELS[condition]}への${OPERATION_LABELS[operation]}は許可されていません。`;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@shivaduke28/gmail-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "gmail-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "tsx --test test/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shivaduke28/gmail-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "gmail",
+    "model-context-protocol"
+  ],
+  "author": "shivaduke",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/shivaduke28/gmail-mcp/issues"
+  },
+  "homepage": "https://github.com/shivaduke28/gmail-mcp#readme",
+  "description": "Gmail MCP server with domain-based permission control",
+  "dependencies": {
+    "@googleapis/gmail": "^16.1.1",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@toon-format/toon": "^2.1.0",
+    "google-auth-library": "^10.5.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}