Ez@work

EZ@Work MCP 服务

将 EZ@Work——面向自由职业者、律师、代理机构和服务型企业的一体化业务管理平台——连接到 Claude、Gemini、Cursor 和任何兼容 MCP 的 AI。

工具

工具	描述	类型
list_clients	列出你的客户／顾客——id、姓名、公司、状态、电子邮件（+ 默认费率）。可选参数：status、search、limit（默认值为 50，最大值为 200）	读取
list_projects	列出你的项目／案件／工单——id、名称、状态、客户。可选参数：status、search、limit	读取
create_client	创建客户；除非 allow_duplicate=true，否则如果可能存在重复项（电子邮件相同，或没有电子邮件时姓名相同）则拒绝创建	写入
log_time_entry	记录项目的可计费工时（0 < hours <= 24），日期为指定的 date（默认为今天）	写入
create_invoice	创建草稿发票，包含 1-50 个明细项（自动设置货币／语言／增值税）	写入

写入工具会修改你 EZ@Work 账户中的数据。工具描述会要求 AI 在调用前与你确认具体值；而且每个工具都会在数据发送到 EZ@Work API 之前验证参数——无效值会返回 {"error": "invalid_input", ...}，后端故障会返回简短的 {"error": ..., "status": ..., "message": ...}（套餐限制会以 PLAN_LIMIT_REACHED 返回）。

列表工具只返回助手选择记录所需的字段——不包含备注、电话号码、增值税号、地址或联系人——并将记录文本标记为用户输入的数据，而非指令。

设置

Claude Desktop / Claude.ai（OAuth — 推荐）

设置 → 连接器 → 添加自定义连接器

• URL：https://mcp.ezatwork.com/mcp
• 身份验证：OAuth（自动）

Claude Code / Cursor / MCP Inspector（API 令牌）

1. 在 https://app.ezatwork.com 创建免费的 EZ@Work 账户
2. 在 https://app.ezatwork.com/settings/api-tokens 生成 API 令牌，并授予以下权限范围： clients:read、clients:write、projects:read、time:write、invoices:write
3. 使用请求头 Authorization: Bearer ezw_pat_... 连接到 https://mcp.ezatwork.com/mcp

使用 MCP Inspector 在本地测试：

npx @modelcontextprotocol/inspector

使用请求头 Authorization: Bearer ezw_pat_... 连接到 http://localhost:8080/mcp

Agent 技能

skills/ezatwork-business-assistant/SKILL.md 指导 Agent 如何安全地使用这些工具：先通过列表解析 ID、每次写入前都与用户确认、将记录文本视为数据，并且绝不声称已发送发票。该技能也收录于 Agensi。

安全

• 你的数据保留在 EZ@Work 账户中
• OAuth 模式：Google 身份 → 查询 EZ@Work 账户；MCP 不存储凭据
• API 令牌模式：令牌必须设置有效期。令牌权限范围正在服务器端强制执行（后端变更正在进行中），因此目前不要仅依靠权限范围来限制令牌。创建令牌时只授予此服务使用的权限范围： clients:read、clients:write、projects:read、time:write、invoices:write
• 每个请求都会验证授权

隐私政策

https://www.ezatwork.com/privacy

通用设计

EZ@Work 会根据你的业务类型进行适配：律师看到“案件”，自由职业者看到“项目”，服务型企业看到“工单”。系统会根据你的个人资料自动检测货币、语言（支持 24 种）和税务规则——无需在 MCP 中进行配置。

---

开发

本地运行

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

cp .env.example .env
# Edit .env: EZ_API_BASE=http://localhost:5000 for local backend

python -m ezatwork_mcp.server
# Server starts at http://localhost:8080/mcp

运行测试

pip install pytest pytest-asyncio
pytest tests/

Docker

docker build -t ezatwork-mcp .
docker run -p 8080:8080 -e EZ_API_BASE=https://api.ezatwork.com ezatwork-mcp

部署到 Cloud Run

gcloud run deploy ezatwork-mcp \
  --source . \
  --region europe-west1 \
  --project ezatwork-production \
  --allow-unauthenticated \
  --port 8080 \
  --update-env-vars "EZ_API_BASE=https://api.ezatwork.com,MCP_BASE_URL=https://mcp.ezatwork.com" \
  --update-secrets "GOOGLE_CLIENT_ID=ezmcp-google-client-id:latest" \
  --update-secrets "GOOGLE_CLIENT_SECRET=ezmcp-google-client-secret:latest" \
  --update-secrets "EZ_MCP_MASTER_TOKEN=ezmcp-master-token:latest"

--allow-unauthenticated 是正确的——身份验证在 MCP 层（OAuth 或 API 令牌）执行，而非在 Cloud Run IAM 层执行。

技术说明

• 传输： Streamable HTTP（/mcp 端点）
• 库： fastmcp 3.x（固定为 <4）
• 身份验证（OAuth）： 使用 fastmcp.server.auth.providers.google 中的 GoogleProvider
• OAuth 重定向允许列表： 客户端只能注册 Claude 的回调地址和环回 URI； 设置 MCP_ALLOWED_REDIRECT_URIS（逗号分隔的模式）以允许其他客户端
• 身份验证（令牌）： 使用 fastmcp.server.dependencies 中的 get_http_headers()
• 双重身份验证： 设置 GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET 和 MCP_BASE_URL 后启用 OAuth
• 后端： 使用 GET /api/users/me 获取区域设置；使用 GET /api/internal/users/by-email 将 OAuth 用户映射到用户
• 列表： GET /api/clients 和 GET /api/projects 不接受筛选条件；状态、搜索和数量限制由 MCP 服务处理，并在返回前精简每条记录
• 工时记录： 使用带有 isBillable 字段的 POST /api/timeentry
• 发票： 使用 POST /api/invoices，并为每个项目计算 dueDate 和 total

---

构建者

EZ@Work —— 为独立从业者打造的业务操作系统。