Winnr

winnr-mcp

Winnr のコールドメールインフラストラクチャ API 用 MCP サーバーです。

Claude（ウェブ、モバイル、デスクトップ）、ChatGPT、Claude Code、Cursor、Windsurf、VS Code （Copilot）、およびその他の MCP クライアントから、自然言語を使ってドメイン、 メールボックス、ウォームアップ、受信トレイ、ウォームアップ済みドメインのマーケットプレイス、Webhook を管理できます。

55 個のツール（うち 26 個は読み取り専用）に加え、8 個のリソースと 5 個のプロンプトプレイブックがあります。

実行方法は 2 通りです。

	ホステッド（推奨）	ローカル
エンドポイント	https://mcp.winnr.app/mcp	stdio 経由の uvx winnr-mcp
認証	Winnr にサインイン（OAuth 2.1 + PKCE）	設定ファイルに API トークンを記載
インストール	不要	uv と、アプリごとの設定ファイル
対応クライアント	claude.ai のウェブ／モバイル、ChatGPT、すべてのデスクトップクライアント	デスクトップクライアントのみ

どちらの方法でも、セットアップはこちら： app.winnr.app/mcp。

---

ホステッドサーバー

https://mcp.winnr.app/mcp をカスタムコネクター／リモート MCP サーバーとして追加します。クライアントが自身を登録し（RFC 7591）、Winnr のサインイン画面に移動するので、許可する操作を選択します。

スコープ	許可される操作
read	すべてを一覧表示し、確認できます。常に許可されます。
write	作成、変更、送信、削除ができます。
purchase	支払いを伴う操作ができます。ドメインの購入、ウォームアップ済みドメインの購入、ウォームアップの有効化が含まれます。

スコープは互いに包含します（purchase ⊃ write ⊃ read）。セッションに表示されるのは、許可されたスコープに対応するツールだけです。各許可は MCP · <client> という名前の通常の API トークンに紐づいているため、ダッシュボードの API ページに表示されます。そこでトークンを取り消すと、アシスタントはアクセスできなくなります。

# Claude Code, hosted
claude mcp add --scope user --transport http winnr https://mcp.winnr.app/mcp

---

クイックスタート（ローカル）

1. トークンを取得する

app.winnr.app/mcp（または API → トークンを作成）で取得します。トークンは wnr_ で始まります。レポートや返信の振り分けだけを行う場合は、読み取り専用を選択してください。作成、送信、購入、削除を行うすべてのツールが、アシスタントに表示されなくなります。WINNR_NO_PURCHASES=true（または --no-purchases）を追加すると、書き込み権限はそのままに、カードに課金する 4 つのツールを非表示にできます。

2. uv をインストールする

サーバーは uvx で実行するため、uv を一度インストールする必要があります。

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh      # or: brew install uv
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

uv がない場合は、pip install winnr-mcp を実行し、引数を指定せずに "command": "winnr-mcp" を使用してください。

3. クライアントにサーバーを追加する

Claude Desktop

設定 → 開発者 → 設定を編集を開き、以下を貼り付けます（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json、Windows の場合は %APPDATA%\Claude\claude_desktop_config.json）。Claude を完全に終了してから、再度開いてください。

{
  "mcpServers": {
    "winnr": {
      "command": "uvx",
      "args": ["winnr-mcp"],
      "env": { "WINNR_API_TOKEN": "wnr_your_token_here" }
    }
  }
}

Claude Code

claude mcp add --scope user winnr -e WINNR_API_TOKEN=wnr_your_token_here -- uvx winnr-mcp

Claude Code 内で /mcp を実行すると、Winnr が接続済みとして表示されます。オプションのガイド付きワークフロー （/winnr setup、/winnr health、/winnr export）は、 winnr-claude-skills から利用できます。

curl -sL https://raw.githubusercontent.com/winnr-app/winnr-claude-skills/main/install.sh | bash

Cursor

~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト）に設定します。JSON は Claude Desktop と同じです。設定 → MCP で、稼働中の Winnr の横に緑色の点が表示されます。

Windsurf

~/.codeium/windsurf/mcp_config.json に設定します。JSON は同じです。設定 → Cascade → MCP Servers で更新してください。

VS Code（Copilot エージェントモード）

.vscode/mcp.json：

{
  "servers": {
    "winnr": {
      "type": "stdio",
      "command": "uvx",
      "args": ["winnr-mcp"],
      "env": { "WINNR_API_TOKEN": "wnr_your_token_here" }
    }
  }
}

4. 試してみる

Winnr アカウントには何があり、残りの容量はどれくらいですか？

アシスタントは winnr_get_account と winnr_get_usage を呼び出します。トークンが使用されると、 app.winnr.app/mcp のページが 接続済み に切り替わります。

設定

ソース	変数／フラグ	説明
環境変数	WINNR_API_TOKEN	必須。 Winnr API トークン（wnr_*）
環境変数	WINNR_API_URL	API ベース URL（デフォルトは https://api.winnr.app。再販業者は独自のホストを使用します）
環境変数	WINNR_TIMEOUT	HTTP タイムアウト（秒）（デフォルトは30。購入時は60）
環境変数	WINNR_READ_ONLY	true にすると、読み書き可能なトークンでも読み取りツールのみを登録します
環境変数	WINNR_NO_PURCHASES	true にすると、書き込みアクセスは維持したまま、金銭を扱う4つのツールを非表示にします
環境変数	WINNR_CONFIRM_SECRET	購入確認トークン用の HMAC キー（ホスト型サーバーでは自動的に設定されます）
CLI	--token, --api-url, --timeout, --read-only, --no-purchases, --version	環境変数を上書きします

CLI 引数は環境変数より優先されます。

起動時に、サーバーは GET /v1/account を呼び出します。トークンが無効な場合は、 明確なメッセージを表示してすぐに終了します（起動後、すべての呼び出しに失敗する サーバーよりも望ましい動作です）。トークンが読み取り専用の場合、書き込みツールは フラグを指定しなくても自動的に非表示になります。

金銭の支出は必ず2段階で行います

カードに請求する4つのツール — winnr_purchase_domains、 winnr_purchase_prewarmed、winnr_purchase_prewarmed_batch、 winnr_enable_warming — は、最初の呼び出しでは請求を行いません。代わりに、 有効な見積もり（在庫状況を再確認し、正確な価格と月額合計を提示）と、10分間有効な confirmation_token を返します。アシスタントが見積もりを提示して明示的な承認を得た後、 トークンを付けて再度呼び出します。その時点で見積もりを再計算し、トークンはその内容に 対する HMAC となるため、価格が変わった場合やドメインが売れてしまった場合は、 予期せぬ請求を行わず、新しい見積もりを提示して購入を拒否します。

アシスタントへのガイダンス

サーバーは instructions をクライアントに送信します（ほとんどのホストはシステム プロンプトに設定します）。また、各ツールには MCP アノテーション（readOnlyHint、 destructiveHint、idempotentHint）が付与されているため、ホストは適切なタイミングで 確認を求めることができます。ガイダンスの内容は次のとおりです。

• ID と非同期ジョブ（job_id → winnr_get_job をポーリング）
• カードに請求する4つのツール（ドメイン購入、事前ウォーム済み購入 ×2、ウォーミング の有効化）と、まず正確な価格を提示して明示的な承認を得るルール。ドメイン購入では、 注文直前に在庫状況と価格を再確認し、変更があれば注文を拒否するため、承認した合計額が 請求額になります
• タイムアウト後は、winnr_list_jobs を確認せずに購入を再試行しないこと
• ドメイン名の適切な取り扱い（ブランド名のような名称や、アウトリーチ／一斉送信／一括 送信を連想させる語句は避ける）
• コールドメールの比率（ドメインあたり2～5個のメールボックス、2～3週間のウォームアップ、 1日あたりの送信数は控えめにする）

また、リソース（ホストが会話に添付できる読み取り専用の記録： winnr://account、winnr://usage、winnr://domains、winnr://domains/{id}、 winnr://domains/{id}/dns-records、winnr://domains/{id}/dns-status、 winnr://warming/overview、winnr://jobs/{id}）と、プロンプト（パラメーター化された プレイブック：winnr_setup_infrastructure、winnr_health_check、winnr_reply_triage、 winnr_connect_own_domain、winnr_scale_up）も提供します。

ツール

権限とは、そのツールに必要なトークンスコープです。読み取りツールはすべてのトークンで表示されます。

アカウント、ジョブ、エクスポート

ツール	説明	権限
winnr_get_account	アカウント、プラン、制限、および呼び出し元のトークンのスコープ	読み取り
winnr_get_usage	ドメイン／メールユーザー／事前ウォームアップ済みアドレスと制限の比較	読み取り
winnr_list_jobs	最近の非同期ジョブ（ステータス／種類でフィルター）	読み取り
winnr_get_job	1 件のジョブのステータス、進捗、結果、エラー	読み取り
winnr_wait_for_job	ジョブが完了するまで待機し、進捗通知をストリーミング	読み取り
winnr_list_export_formats	対応している CSV 形式	読み取り
winnr_export_email_users	認証情報の CSV（15 分間有効なリンク）、22 種類のシーケンサー形式	書き込み

ドメイン

ツール	説明	権限
winnr_list_domains	ドメインの一覧（ページネーション対応、任意のステータスフィルター：complete、pending、…）	読み取り
winnr_get_domain	DNS ステータスと稼働状況を含む 1 件のドメイン	読み取り
winnr_search_domains	1 つの名前の空き状況と価格	読み取り
winnr_search_domains_bulk	最大 100 個の名前の空き状況と価格	読み取り
winnr_get_dns_status	プロビジョニング／伝播の状態（MX、SPF、DKIM、DMARC）	読み取り
winnr_get_dns_records	手動 DNS のドメインに追加するレコード	読み取り
winnr_check_dns_provider	現在ドメインの DNS がホストされている場所（1 回あたり最大 20 件）	読み取り
winnr_purchase_domains	ドメインの購入とセットアップ（見積もり → 確認、カードに請求されます）	購入
winnr_setup_domain	DNS／メールのプロビジョニングを再実行し、メールボックス／転送を追加	書き込み
winnr_connect_domains	独自ドメインを接続（ネームサーバー、手動 DNS、または Cloudflare トークン）	書き込み
winnr_check_nameservers	NS の変更を確認し、プロビジョニングを自動でキューに追加	書き込み
winnr_verify_dns	手動 DNS レコードをライブ検証	書き込み
winnr_tag_domains	最大 50 件のドメインにタグを追加／削除／設定	書き込み
winnr_delete_domain	ドメインとそのメールボックスを削除（破壊的操作）	書き込み

メールボックス（メールユーザー）

ツール	説明	権限
winnr_list_email_users	メールボックスの一覧。ドメインでフィルター可能	読み取り
winnr_get_email_user	IMAP／SMTP の詳細を含む 1 件のメールボックス	読み取り
winnr_create_email_user	1 件のメールボックスを作成（非同期ジョブ）	書き込み
winnr_bulk_create_email_users	1 つのドメインに最大 100 件のメールボックスを作成	書き込み
winnr_update_email_user	名前の変更またはパスワードの設定	書き込み
winnr_delete_email_user	メールボックスを削除（破壊的操作）	書き込み

受信トレイ

ツール	説明	権限
winnr_list_inbox	すべてのメールボックスのメッセージ。ウォームアップメールはデフォルトで非表示	読み取り
winnr_get_message_body	uid + mailbox で本文全体を取得（10k 文字で切り捨て）	読み取り
winnr_send_email	スレッドヘッダーを付けてメールボックスから送信	書き込み
winnr_refresh_inbox	同期を開始	書き込み
winnr_delete_message	1 件のメッセージを削除（破壊的操作）	書き込み

ウォームアップ

ツール	説明	権限
winnr_list_warming	ウォームアップ中のすべてのメールボックスと健全性／受信率	読み取り
winnr_get_warming_overview	集計統計と推定月額費用	読み取り
winnr_get_warming_metrics	1 件のメールボックスの日次系列	読み取り
winnr_enable_warming	有効化。emails_per_day は 1～20、rampup_speed（見積もり → 確認、メールボックス 1 件あたり月額 $0.60）	購入
winnr_disable_warming	無効化して請求を停止	書き込み
winnr_pause_warming / winnr_resume_warming	一時停止／再開	書き込み
winnr_update_warming_settings	emails_per_day、rampup_enabled、rampup_speed	書き込み

ウォームアップ済みマーケットプレイス

ツール	説明	権限
winnr_browse_prewarmed	利用可能な、運用期間が長くウォームアップ済みのドメイン	読み取り
winnr_get_prewarmed_domain	1つの掲載ドメインのアドレスごとの健全性	読み取り
winnr_check_prewarmed_blocklist	ブロックリストのリアルタイム確認（9件のリスト）	読み取り
winnr_list_my_prewarmed	購入済みのウォームアップ済みドメイン	読み取り
winnr_purchase_prewarmed	ドメインを1つ購入（アドレスあたり月額$3、見積もり → 確定、カードに課金されます）	購入
winnr_purchase_prewarmed_batch	最大25個のドメインを1回の請求で購入（見積もり → 確定、カードに課金されます）	購入
winnr_cancel_prewarmed	ドメインを解約して返却（取り消し不可）	書き込み

Webhook

ツール	説明	権限
winnr_list_webhooks	ステータスと健全性を含むエンドポイント	読み取り
winnr_get_webhook_deliveries	最近の配信試行	読み取り
winnr_create_webhook	作成（レスポンスに署名シークレットが含まれます）	書き込み
winnr_update_webhook	URL／イベント／説明／ステータスを変更	書き込み
winnr_test_webhook	test.ping を送信	書き込み
winnr_rotate_webhook_secret	シークレットをローテーション（古いシークレットは24時間有効）	書き込み
winnr_get_webhook_secret	署名シークレットを読み取り（機密情報のため、読み取り専用トークンでは非表示）	書き込み
winnr_delete_webhook	削除（取り消し不可）	書き込み

エラー

すべてのツールはJSONを返します。失敗時は次のようになります。

{ "error": { "message": "Payment required: …", "status_code": 402, "code": "payment_method_required" } }

エージェントは code に基づいて分岐できます。読み取り専用での403エラーでは、トークンに書き込みスコープがないことが説明されます。読み取りでの429エラーは自動的に1回再試行されます。

セキュリティ

• トークンの権限が適用されます。 すべての操作は1つのアカウントとして、トークンの権限で実行されます。 ダッシュボードでトークンを失効させると、アシスタントは即座にアクセスできなくなります。
• パスワードがツールの出力に表示されることはありません。 認証情報が外部に出るのは、 読み取り／書き込みトークンが必要な、15分間有効の署名付きCSVリンクを返す winnr_export_email_users のみです。
• ログは一切記録されません。 トークンはベアラーヘッダーとして送信され、出力されることはありません。 サーバーは起動時にstderrへ1行だけ書き込みます。
• レート制限はAPIの制限に準じます（Startupは300リクエスト／分、Enterpriseは500リクエスト／分）。サーバーは、ウィンドウ内の残りリクエスト数が10未満になると警告します。

開発

git clone https://github.com/winnr-app/winnr-mcp.git
cd winnr-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest          # 124 tests, all HTTP mocked (incl. the full OAuth flow)
ruff check src tests
WINNR_API_TOKEN=wnr_xxx python -m winnr_mcp   # run locally over stdio

# the hosted server, locally
pip install -e ".[remote]"
uvicorn --factory winnr_mcp.remote.app:create_app --port 8000

ホスト型サーバーのデプロイ

python scripts/deploy_remote.py はAWS上のすべてのリソース（OAuth状態用のDynamoDBテーブル、SSMシークレット、arm64 Lambdaとレイヤー、HTTP API、ACM証明書、mcp.winnr.app ドメインとRoute53エイリアス）をプロビジョニングし、デプロイを検証します。

ライセンス

MIT