Secure Payslip Downloader

MCP文档知识

提供方 GalSened

文档知识 stdio · 本地进程 OAuth 授权 社区 / 第三方 Claude DesktopClaude
查看接入方式

一个通过Gmail API自动下载PDF工资单的安全工具,支持定时任务和Claude桌面集成。

一句话选型结论

按资料字段整理

Secure Payslip Downloader 属于文档知识类 MCP 服务器,stdio · 本地进程,OAuth 授权,可直接接入 Claude Desktop、Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类文档知识 传输方式stdio · 本地进程 鉴权OAuth 授权 部署方式本地部署
GitHub 星标 0 仓库热度,无公开仓库时显示未标注
工具数 5 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

文档知识
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量5暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

工资单管理Python本地部署自动化工具Gmail集成PDF处理安全下载

安装与配置

stdio · 本地进程 OAuth 授权
客户端在本机拉起子进程,数据不出本机
uv run python scripts/oauth_setup.py

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Python,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 5 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
文档检索问答

在你的文档库里按问题找答案。

知识库读写

把新资料写进知识库,随用随取。

内容整理

把零散资料归纳成结构化笔记。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 5 个工具,职责相对集中,接入后不容易误操作。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好OAuth 授权对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在文档知识场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Secure Payslip Downloader当前 5 stdio · 本地进程 本地部署 有 2026-05-17
dify 未标注 stdio · 本地进程 本地部署 有 2026-04-11
open-webui 未标注 stdio · 本地进程 本地部署 有 2026-04-11
JeecgBoot 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Cherry Studio 未标注 未标注 未标注 无 2026-05-17
mempalace 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

文档知识
字段来自项目仓库与公开索引,中文说明由本站标注
提供方GalSened上游标注的维护方 GalSened
分类文档知识本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式OAuth 授权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Python本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

10.7 KB
来自项目仓库与上游目录的原文,未做删改

安全工资单下载器

通过与Claude Desktop集成,从Gmail自动下载每月工资单。

一个安全的MCP(模型上下文协议)服务器,使用OAuth身份验证自动从Gmail下载PDF工资单,并支持通过cron进行定时下载。

✨ 特性

  • 🔒 安全OAuth 2.0身份验证 -带有只读访问功能的Gmail API
  • 📅 每月自动下载 -使用系统cron设置并忘记
  • 🤖 Claude桌面集成 -5个用于交互式管理的MCP工具
  • 📁 有序存储 -按年份保存的文件: ~/Documents/Payslips/YYYY/
  • 🔐 安全第一设计 -文件权限、路径遍历阻止、凭据编辑
  • 📄 PDF验证 -Magic bytes验证确保只下载PDF
  • 🌍 时区支持 -已配置为以色列时区(亚洲/耶路撒冷)
  • 📊 综合录井 -所有记录了敏感数据的操作均已编辑

🏗️ 建筑```

secure-payslip-downloader/
├── src/
│ ├── server.py # FastMCP server with 5 tools
│ ├── gmail_client.py # Gmail API with OAuth & rate limiting
│ ├── scheduler.py # Schedule management (JSON-based)
│ ├── config.py # Configuration management
│ └── security.py # Security utilities
├── scripts/
│ ├── oauth_setup.py # OAuth authentication wizard
│ ├── run_scheduled_downloads.py # Cron runner script
│ └── test_scheduler.py # Scheduler tests
├── credentials/ # OAuth credentials (gitignored)
├── schedules/ # Schedule storage (gitignored)
├── logs/ # Application logs (gitignored)
└── pyproject.toml # uv dependencies


## 🚀 快速开始

### 先决条件

1. **Python 3.9+** 随着 紫外线 安装
1. **谷歌云项目** 启用Gmail API
1. **Claude桌面版** (用于MCP集成)

### 安装```bash
# 1. Clone or navigate to project directory
cd /Users/galsened/secure-payslip-downloader

# 2. Install dependencies (already done if using uv)
uv sync

# 3. Set up Google OAuth (see GOOGLE_CLOUD_SETUP.md)
# Download credentials.json to credentials/

# 4. Run OAuth setup
uv run python scripts/oauth_setup.py

# 5. Add MCP server to Claude Desktop
# See "Claude Desktop Configuration" section below

Claude桌面配置

将此添加到您的 ~/Library/Application Support/Claude/claude_desktop_config.json:```json
{
"mcpServers": {
"secure-payslip-downloader": {
"command": "uv",
"args": [
"--directory",
"/Users/galsened/secure-payslip-downloader",
"run",
"python",
"src/server.py"
],
"env": {
"GMAIL_CREDS_PATH": "/Users/galsened/secure-payslip-downloader/credentials/credentials.json",
"DOWNLOAD_BASE_PATH": "/Users/galsened/Documents/Payslips",
"TIMEZONE": "Asia/Jerusalem",
"LOG_LEVEL": "INFO"
}
}
}
}


**注:** 如果安装到其他位置,请更新路径。

## 🛠️ MCP工具

服务器提供了5个可通过Claude Desktop访问的工具:

### 1. `search_payslip_email`

搜索来自特定发件人的工资单电子邮件。```javascript
search_payslip_email(
sender_email="payroll@company.com",
subject_keywords="payslip",  // optional
days_back=30                 // optional
)

退货: 带有附件元数据的匹配电子邮件列表。

2. download_payslip

下载特定的PDF附件。```javascript
download_payslip(
message_id="18f3a4b5c6d7e8f9",
attachment_id="ANGjdJ8...",
filename="Payslip_November_2025.pdf"
)


**退货:** 下载状态和文件路径。

### 3. `create_monthly_schedule`

创建自动月度下载计划。```javascript
create_monthly_schedule(
sender_email="payroll@company.com",
day_of_month=11,
hour=9,                      // optional, default: 9
minute=0,                    // optional, default: 0
subject_keywords="payslip",  // optional
description="Monthly payslip from Company Ltd"  // optional
)

退货: 计划ID和cron设置说明。

4. list_schedules

列出所有已配置的计划。```javascript
list_schedules(
enabled_only=false // optional
)


**退货:** 所有带有状态和统计信息的日程表。

### 5. `delete_schedule`

删除计划下载。```javascript
delete_schedule(
schedule_id="abc123..."
)

退货: 删除确认。

📅 设置自动下载

第一步:通过Claude创建日程表```

You: Create a monthly schedule to download payslips from payroll@company.com
on the 11th of each month at 9 AM with subject keyword "payslip"


克劳德将使用 `create_monthly_schedule` 工具并返回cron命令。

### 步骤2:添加到Crontab```bash
# Edit crontab
crontab -e

# Add the cron command from Step 1 (example):
0 9 11 * * cd /Users/galsened/secure-payslip-downloader && uv run python scripts/run_scheduled_downloads.py >> logs/cron.log 2>&1

# Save and exit

步骤3:验证```bash

Check crontab entry

crontab -l

Test manually

uv run python scripts/run_scheduled_downloads.py

Check logs

tail -f logs/cron.log


有关详细的cron设置说明,请参阅 CRON_SETUP.md.

## 📖 使用示例

### 示例1:一次性下载```
You: Search for payslips from payroll@mycompany.com in the last 7 days

Claude: [Uses search_payslip_email tool]
Found 1 email with 1 PDF attachment: "Payslip_November_2025.pdf"

You: Download it

Claude: [Uses download_payslip tool]
Downloaded to: ~/Documents/Payslips/2025/Payslip_November_2025.pdf

示例2:设置自动化```

You: Set up automatic monthly download from hr@company.com on the 11th at 9 AM

Claude: [Uses create_monthly_schedule tool]
Schedule created! Add this to your crontab:
0 9 11 * * cd /path/to/project && uv run python scripts/run_scheduled_downloads.py >> logs/cron.log 2>&1

You: [Adds to crontab]


### 示例3:管理时间表```
You: Show me all my scheduled downloads

Claude: [Uses list_schedules tool]
You have 2 active schedules:
1. Company A payslips - Every 11th at 09:00
2. Company B payslips - Every 15th at 14:00

You: Delete the first one

Claude: [Uses delete_schedule tool]
Schedule deleted successfully

🔒 安全特性

认证

  • 仅限OAuth 2.0 -没有密码或API密钥
  • Gmail只读范围 -无法修改或删除电子邮件
  • 安全令牌存储 -token.pickle上的0600权限
  • 自动令牌刷新 -无需人工干预

文件安全性

  • 路径遍历预防 -文件名清理
  • 安全权限 -敏感目录为0700,文件为0600
  • PDF验证 -魔术字节检查(%PDF-)
  • 有组织的存储 -按年份分组的文件

日志安全

  • 凭证编辑 -令牌、密码、API密钥被屏蔽
  • 电子邮件部分编辑 -日志中仅显示域
  • 安全日志权限 -日志目录上的0700

速率限制

  • 5次呼叫/秒 用于搜索操作
  • 3次呼叫/秒 下载
  • 指数退避 API错误(429500503)

🧪 测试

运行综合测试套件:```bash

Test scheduler module

uv run python scripts/test_scheduler.py

Test OAuth setup (requires credentials.json)

uv run python scripts/oauth_setup.py

Test cron runner (requires OAuth token)

uv run python scripts/run_scheduled_downloads.py

Verify MCP server

uv run python -c "import sys; sys.path.insert(0, 'src'); from server import mcp; print('✓ MCP server OK')"


## 📁 文件组织

### 下载```
~/Documents/Payslips/
├── 2024/
│   ├── Payslip_December_2024.pdf
│   └── Payslip_November_2024.pdf
└── 2025/
├── Payslip_January_2025.pdf
└── Payslip_February_2025.pdf

日程表

存储在 schedules/tasks.json:```json
{
"abc123-456": {
"sender_email": "payroll@company.com",
"subject_keywords": "payslip",
"schedule": "0 9 11 * *",
"enabled": true,
"created_at": "2025-01-15T10:30:00",
"last_run": "2025-02-11T09:00:05",
"description": "Monthly payslip from Company Ltd"
}
}


### 日志

- `logs/app.log` -应用程序日志
- `logs/cron.log` -Cron执行日志

## ⚙️ 配置

### 环境变量

- `GMAIL_CREDS_PATH` -credentials.json的路径(默认: `credentials/credentials.json`)
- `DOWNLOAD_BASE_PATH` -基本下载目录(默认: `~/Documents/Payslips`)
- `TIMEZONE` -日程安排的时区(默认值: `Asia/Jerusalem`)
- `LOG_LEVEL` -日志记录级别(默认值: `INFO`)

### 目录结构

敏感目录(凭据、计划、日志)使用0700权限。
下载目录使用0755权限。

## 🐛 故障排除

### OAuth身份验证失败```bash
# Re-run OAuth setup
uv run python scripts/oauth_setup.py

# Check credentials exist
ls -l credentials/credentials.json

# Check permissions
chmod 600 credentials/credentials.json

Cron作业未运行```bash

Check crontab

crontab -l

Check cron service (macOS)

sudo launchctl list | grep cron

Check logs

tail -50 logs/cron.log

Test manually

uv run python scripts/run_scheduled_downloads.py


### 未找到电子邮件```bash
# Test search via Claude Desktop
# Use: search_payslip_email tool

# Check Gmail API quota
# Visit: Google Cloud Console > APIs & Services > Quotas

# Verify sender email is exact
# Gmail search is case-sensitive for email addresses

下载失败```bash

Check disk space

df -h ~/Documents/Payslips

Check permissions

ls -ld ~/Documents/Payslips
ls -ld ~/Documents/Payslips/2025

Check logs for details

grep ERROR logs/app.log
```

📚 文档

  • CRON_SETUP.md -详细的cron配置指南
  • GOOGLE_CLOUD_SETUP.md -谷歌云项目设置(即将推出)
  • .env.示例 -环境变量模板

🔗 依赖项

  • fastmcp -MCP服务器框架
  • 谷歌认证 -OAuth身份验证
  • googleapi-python客户端 -Gmail API客户端
  • python日期工具 -日期/时间实用程序
  • 皮丹提克 -数据验证

中的完整依赖关系列表 pyproject.toml.

📋 需求

  • Python 3.9或更高版本
  • macOS或Linux(带WSL的Windows)
  • 具有OAuth凭据的Gmail帐户
  • Claude Desktop(用于MCP集成)

🤝 贡献

这是一个个人工具,但请随时根据您的需求进行分叉和调整。

📄 许可证

MIT许可证-有关详细信息,请参阅许可证文件。

⚠️ 重要提示

  1. OAuth令牌安全:
  • 永不承诺 credentials/ 目录
  • 永远不要分享你的 token.pickle 文件
  • 令牌提供只读Gmail访问
  1. Cron环境:
  • Cron在最小环境下运行
  • 始终使用绝对路径
  • 首先手动测试cron命令
  1. Gmail API限制:
  • 免费等级:10亿配额单位/天
  • 搜索:5个单位/请求
  • 下载:10个单位/请求
  • 典型使用量:~1000台/月
  1. 文件组织:
  • 按电子邮件日期年份组织的文件
  • 自动跳过重复文件
  • 保留(净化)原始文件名

🙏 致谢

内置:

  • FastMCP 马文·普雷弗克特
  • Gmail API 通过谷歌
  • 紫外线 by阿斯特拉

状态: ✅ 完全实施和测试

最后更新时间: 2025-01-29

如需支持或疑问,请在GitHub上发布问题。

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Secure Payslip Downloader 怎么安装?

在客户端按下面的安装命令接入:uv run python scripts/oauth_setup.py。装完在客户端配置里引用同一个包或端点。

Secure Payslip Downloader 怎么在 Claude Desktop、Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Secure Payslip Downloader 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Secure Payslip Downloader 需要 API Key 吗?

资料标注需要OAuth 授权认证,使用前准备好对应凭据,并按最小权限配置。

Secure Payslip Downloader 支持哪些客户端?

资料标注支持 Claude Desktop、Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Secure Payslip Downloader 能提供哪些能力?

资料显示约 5 个工具;能力标签包括 Python、Claude、Gmail集成。具体工具清单以官方文档为准。

Secure Payslip Downloader 需要什么运行环境?

运行时为 Python;属于本地进程,需要在本机装好运行环境。

Secure Payslip Downloader 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。