AI导哈

Gmail MCP服务器

一个使用Nix flakes和agenix加密凭证管理的Gmail MCP服务器实现。

  • by colonelpanic8
  • Nix
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 colonelpanic8/gmail-mcp

使用说明

Gmail MCP服务器

一种用于运行的镍片 Gmail MCP服务器 通过agenix管理加密凭据。

项目结构

gmail-mcp/
├── flake.nix                              # Nix flake with all scripts and dependencies
├── flake.lock                             # Locked dependencies
├── secrets.nix                            # Age public keys for encryption
├── secrets/
│   ├── gmail-oauth-credentials.json.age   # Encrypted Google OAuth client credentials
│   └── gmail-oauth-token.json.age         # Encrypted OAuth refresh token
├── .gitignore                             # Excludes unencrypted secrets
└── .envrc                                 # direnv configuration

先决条件

  • 启用薄片的Nix
  • SSH ed25519密钥位于 ~/.ssh/id_ed25519
  • direnv（可选但推荐）

快速启动（现有设置）

如果加密密钥已经存在，并且您的SSH密钥在 secrets.nix:

git clone https://github.com/colonelpanic8/gmail-mcp.git
cd gmail-mcp
direnv allow  # or: nix develop
gmail-mcp-setup  # Decrypts credentials to ~/.gmail-mcp/

然后配置克劳德代码：

claude mcp add --scope user gmail -- nix run github:colonelpanic8/gmail-mcp

初始设置（新安装）

1.克隆并进入开发shell

git clone https://github.com/colonelpanic8/gmail-mcp.git
cd gmail-mcp
direnv allow  # or: nix develop

2.设置谷歌云OAuth

  1. 在以下位置创建Google Cloud项目https://console.cloud.google.com
  2. 启用Gmail API
  3. 配置OAuth同意屏幕（外部，将您的电子邮件添加为测试用户）
  4. 创建OAuth凭据（桌面应用程序）
  5. 下载JSON凭据

3.将您的年龄公钥添加到secrets.nix

# Get your age public key from your SSH key
ssh-to-age < ~/.ssh/id_ed25519.pub

# Edit secrets.nix and replace/add your public key

4.加密您的凭据

# Encrypt the OAuth client credentials
age -r "YOUR_AGE_PUBLIC_KEY" -o secrets/gmail-oauth-credentials.json.age credentials.json

# Remove the unencrypted file
rm credentials.json

5.使用Gmail进行身份验证

gmail-mcp-setup  # Decrypts credentials to ~/.gmail-mcp/
npx @gongrzhe/server-gmail-autoauth-mcp auth  # Opens browser for OAuth
gmail-mcp-encrypt-token  # Encrypts the token for portability
git add secrets/gmail-oauth-token.json.age && git commit -m "Add encrypted token"

命令

命令 描述
gmail-mcp-setup 解密凭据和令牌 ~/.gmail-mcp/
gmail-mcp-server 运行Gmail MCP服务器
gmail-mcp-encrypt-token OAuth身份验证后加密令牌

测试设置

# Verify credentials are decrypted
ls -la ~/.gmail-mcp/
# Should show: gcp-oauth.keys.json and credentials.json

# Test the server starts (Ctrl+C to stop)
gmail-mcp-server

# The server communicates via stdio - it will appear to hang waiting for input
# This is normal. Use Ctrl+C to exit.

环境变量

变量 默认值 描述
GMAIL_MCP_SECRETS_DIR ~/.gmail-mcp 解密凭据目录
SSH_KEY ~/.ssh/id_ed25519 用于年龄解密的SSH密钥
GMAIL_MCP_REPO 当前目录 加密令牌的回购路径

添加其他用户

要允许另一个人/机器解密这些秘密：

  1. 获取他们的年龄公钥： ssh-to-age < their_key.pub
  2. 添加到 secrets.nix
  3. 使用所有密钥重新加密机密：
agenix -r  # Re-encrypts all secrets with updated keys

故障排除

“找不到凭据文件”

  • 确保您正在从repo目录运行命令
  • 或设置 GMAIL_MCP_REPO=/path/to/gmail-mcp

“年龄：错误：没有与任何收件人匹配的身份”

  • 您的SSH密钥与中的任何公钥都不匹配 secrets.nix
  • 将您的年龄公钥添加到 secrets.nix 然后跑 agenix -r

OAuth令牌已过期

npx @gongrzhe/server-gmail-autoauth-mcp auth  # Re-authenticate
gmail-mcp-encrypt-token  # Re-encrypt the new token

安全说明

  • OAuth凭据和令牌随年龄加密，可以安全提交
  • 只有在中具有匹配SSH密钥的用户 secrets.nix 可以解密
  • 存储在中的解密凭据 ~/.gmail-mcp/ 从git中排除
  • 这 .age 文件使用age加密，SSH密钥通过SSH转换为age

对于AI代理

本节为使用此仓库的AI编码助手提供上下文。

关键文件

  • flake.nix -包含所有shell脚本(gmail-mcp-setup, gmail-mcp-server, gmail-mcp-encrypt-token)作为Nix衍生物
  • secrets.nix -可以解密秘密的年龄公钥列表
  • secrets/*.age -加密文件（凭据和OAuth令牌）

常见任务

用户想要使用Gmail MCP：

  1. 确保 gmail-mcp-setup 已运行（检查 ~/.gmail-mcp/credentials.json)
  2. MCP服务器可通过以下方式访问 nix run github:colonelpanic8/gmail-mcp

用户需要添加新机器/人员：

  1. 获取他们的年龄公钥： ssh-to-age < ~/.ssh/id_ed25519.pub
  2. 添加到 secrets.nix
  3. 跑 agenix -r 重新加密

OAuth令牌已过期：

  1. 跑 npx @gongrzhe/server-gmail-autoauth-mcp auth
  2. 跑 gmail-mcp-encrypt-token
  3. 提交更新 .age 文件

什么不该做

  • 从不以未加密的方式提交 .json 文件在 secrets/
  • 切勿公开解密凭据的内容
  • 不修改加密 .age 直接文件-使用age/agenix命令

相关 MCP