# Directory Structure
```
├── .gitignore
├── biome.json
├── code.gs
├── index.ts
├── LICENSE
├── package-lock.json
├── package.json
├── README.md
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 | dist
2 | node_modules
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Gmail
2 |
3 | Model Context Protocol server for Gmail integration. This allows Claude Desktop (or any MCP client) to interact with your Gmail account through Google Apps Script.
4 |
5 | <a href="https://glama.ai/mcp/servers/7awla69pjq"><img width="380" height="200" src="https://glama.ai/mcp/servers/7awla69pjq/badge" alt="@kazuph/mcp-gmail-gas MCP server" /></a>
6 |
7 | ## Quick Start (For Users)
8 |
9 | ### Prerequisites
10 | - Node.js 18+ (install via `brew install node`)
11 | - Gmail account
12 | - Google Apps Script deployment
13 | - Claude Desktop (install from https://claude.ai/desktop)
14 |
15 | ### Configuration
16 |
17 | 1. Deploy the Google Apps Script
18 | - Visit [Google Apps Script](https://script.google.com/) and create a new project
19 | - Copy the entire contents of `code.gs` and paste it into the script editor
20 | - Click on "Deploy" > "New deployment"
21 | - Select "Web app" as the deployment type
22 | - Configure the following settings:
23 | - Execute as: Me
24 | - Who has access: Anyone
25 | - Click "Deploy"
26 | - When prompted, review and authorize the app to access your Gmail account
27 | - Copy the deployment URL and generate a random API key for security
28 |
29 | Note: The script requires Gmail access permissions. When you first deploy and run the script, Google will ask you to review and grant these permissions. Make sure to:
30 | 1. Click "Review Permissions"
31 | 2. Select your Google account
32 | 3. Click "Advanced" if you see a warning
33 | 4. Click "Go to [Your Project Name] (unsafe)"
34 | 5. Click "Allow" to grant the necessary Gmail permissions
35 |
36 | 2. Open your Claude Desktop configuration file at:
37 | `~/Library/Application Support/Claude/claude_desktop_config.json`
38 |
39 | You can find this through the Claude Desktop menu:
40 | 1. Open Claude Desktop
41 | 2. Click Claude on the Mac menu bar
42 | 3. Click "Settings"
43 | 4. Click "Developer"
44 |
45 | 3. Add the following to your configuration:
46 |
47 | ```json
48 | {
49 | "tools": {
50 | "gmail": {
51 | "command": "npx",
52 | "args": ["-y", "@kazuph/mcp-gmail-gas"],
53 | "env": {
54 | "GAS_ENDPOINT": "YOUR_DEPLOYMENT_URL",
55 | "VALID_API_KEY": "YOUR_API_KEY"
56 | }
57 | }
58 | }
59 | }
60 | ```
61 |
62 | Note: Replace `YOUR_DEPLOYMENT_URL` and `YOUR_API_KEY` with your actual values.
63 |
64 | ## For Developers
65 |
66 | ### Prerequisites
67 | - Node.js 18+ (install via `brew install node`)
68 | - Gmail account
69 | - Google Apps Script
70 | - Claude Desktop (install from https://claude.ai/desktop)
71 | - tsx (install via `npm install -g tsx`)
72 |
73 | ### Installation
74 |
75 | ```bash
76 | git clone https://github.com/kazuph/mcp-gmail-gas.git
77 | cd mcp-gmail-gas
78 | npm install
79 | npm run build
80 | ```
81 |
82 | ### Development Configuration
83 |
84 | 1. Make sure Claude Desktop is installed and running.
85 |
86 | 2. Install tsx globally if you haven't:
87 | ```bash
88 | npm install -g tsx
89 | # or
90 | pnpm add -g tsx
91 | ```
92 |
93 | 3. Modify your Claude Desktop config located at:
94 | `~/Library/Application Support/Claude/claude_desktop_config.json`
95 |
96 | Add the following to your MCP client's configuration:
97 |
98 | ```json
99 | {
100 | "tools": {
101 | "gmail": {
102 | "args": ["tsx", "/path/to/mcp-gmail-gas/index.ts"],
103 | "env": {
104 | "GAS_ENDPOINT": "YOUR_DEPLOYMENT_URL",
105 | "VALID_API_KEY": "YOUR_API_KEY"
106 | }
107 | }
108 | }
109 | }
110 | ```
111 |
112 | ## Available Tools
113 |
114 | - `gmail_search_messages`: Search for emails using Gmail search query syntax (e.g., "subject:Meeting newer_than:1d")
115 | - `gmail_get_message`: Get the full content and details of a specific email
116 | - `gmail_download_attachment`: Download an attachment from a specific email
117 |
118 | ## Security Note
119 |
120 | Always keep your `VALID_API_KEY` secret and never commit it to version control. This key helps ensure that only authorized clients can access your Gmail through the Google Apps Script deployment.
121 |
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "compilerOptions": {
3 | "target": "ES2022",
4 | "strict": true,
5 | "esModuleInterop": true,
6 | "skipLibCheck": true,
7 | "forceConsistentCasingInFileNames": true,
8 | "resolveJsonModule": true,
9 | "outDir": "./dist",
10 | "rootDir": ".",
11 | "moduleResolution": "NodeNext",
12 | "module": "NodeNext"
13 | },
14 | "exclude": ["node_modules"],
15 | "include": ["./**/*.ts"]
16 | }
17 |
```
--------------------------------------------------------------------------------
/biome.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "$schema": "https://biomejs.dev/schemas/1.5.3/schema.json",
3 | "organizeImports": {
4 | "enabled": true
5 | },
6 | "linter": {
7 | "enabled": true,
8 | "rules": {
9 | "recommended": true
10 | }
11 | },
12 | "formatter": {
13 | "enabled": true,
14 | "indentStyle": "space",
15 | "indentWidth": 2,
16 | "lineWidth": 80
17 | },
18 | "javascript": {
19 | "formatter": {
20 | "quoteStyle": "double",
21 | "trailingComma": "es5",
22 | "semicolons": "always"
23 | }
24 | }
25 | }
26 |
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "name": "@kazuph/mcp-gmail-gas",
3 | "version": "1.1.2",
4 | "description": "Model Context Protocol server for Gmail",
5 | "author": "kazuph (https://x.com/kazuph)",
6 | "main": "dist/index.js",
7 | "type": "module",
8 | "bin": {
9 | "mcp-gmail": "dist/index.js"
10 | },
11 | "files": [
12 | "dist"
13 | ],
14 | "scripts": {
15 | "build": "tsc && shx chmod +x dist/*.js",
16 | "prepare": "npm run build",
17 | "watch": "tsc --watch"
18 | },
19 | "repository": {
20 | "type": "git",
21 | "url": "git+https://github.com/kazuph/mcp-gmail-gas.git"
22 | },
23 | "keywords": [
24 | "gmail",
25 | "mcp",
26 | "claude"
27 | ],
28 | "license": "MIT",
29 | "publishConfig": {
30 | "access": "public"
31 | },
32 | "dependencies": {
33 | "@modelcontextprotocol/sdk": "0.5.0",
34 | "glob": "^10.3.10",
35 | "zod": "^3.23.8",
36 | "zod-to-json-schema": "^3.23.5"
37 | },
38 | "devDependencies": {
39 | "@types/node": "^20.11.0",
40 | "shx": "^0.3.4",
41 | "typescript": "^5.3.3"
42 | }
43 | }
44 |
```