Ez@work

EZ@Work MCP サーバー

EZ@Work（EZ@Work）をClaude、Gemini、 Cursor、およびMCP互換のあらゆるAIに接続します。EZ@Workは、フリーランサー、 弁護士、代理店、サービス業向けのオールインワンのビジネス管理サービスです。

ツール

ツール	説明	種類
list_clients	クライアント／顧客の一覧を取得します。id、名前、会社、ステータス、メールアドレス（＋デフォルト料金）が含まれます。status、search、limit（デフォルトは50、最大200）を指定できます	読み取り
list_projects	プロジェクト／案件／作業依頼の一覧を取得します。id、名前、ステータス、クライアントが含まれます。status、search、limitを指定できます	読み取り
create_client	クライアントを作成します。allow_duplicate=trueを指定しない限り、重複の可能性がある場合（同じメールアドレス、またはメールアドレスがない場合は同じ名前）は作成しません	書き込み
log_time_entry	指定したdate（デフォルトは今日）のプロジェクトに請求対象時間を記録します（0 < hours <= 24）	書き込み
create_invoice	下書き請求書を作成します。明細は1～50件で、通貨／言語／VATは自動設定されます	書き込み

書き込みツールはEZ@Workアカウントのデータを変更します。各ツールの説明では、 呼び出し前にAIが正確な値をユーザーに確認するよう指示しています。また、 すべてのツールは、EZ@Work APIに送信する前に引数を検証します。不正な値の場合は {"error": "invalid_input", ...}が返され、バックエンドでエラーが発生した場合は 簡潔な{"error": ..., "status": ..., "message": ...}が返されます（プランの上限は PLAN_LIMIT_REACHEDとしてそのまま返されます）。

一覧取得ツールは、アシスタントがレコードを選ぶために必要なフィールドのみを返します。 メモ、電話番号、VAT番号、住所、連絡先は含まれません。また、レコードのテキストは 指示ではなくユーザーが入力したデータとして扱うよう明示されます。

セットアップ

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に接続します

エージェントスキル

skills/ezatwork-business-assistant/SKILL.mdは、 これらのツールを安全に使う方法をエージェントに教えます。最初に一覧を取得してIDを特定する、 書き込みのたびにユーザーに確認する、レコードのテキストをデータとして扱う、 請求書を送信したと決して主張しない、といった内容です。また、Agensiにも掲載されています。

セキュリティ

• データはEZ@Workアカウント内に保持されます
• OAuthモード：GoogleのIDから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は正しい設定です。認証はCloud RunのIAMレベルではなく、MCPレイヤー（OAuthまたはAPIトークン）で適用されます。

技術的なメモ

• トランスポート： ストリーミング可能な 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、OAuth からユーザーへのマッピングには GET /api/internal/users/by-email
• リスト： GET /api/clients と GET /api/projects はフィルターを受け付けません。ステータス、検索、上限は MCP サーバーで適用され、各レコードは返却前に必要な項目に絞られます。
• 時間エントリー： isBillable フィールドを指定して POST /api/timeentry
• 請求書： アイテムごとに算出した dueDate と total を指定して POST /api/invoices

---

制作

EZ@Work — 個人事業主のためのビジネス OS。