Mac Claw API完全ガイド：全57ツール解説

Mac Claw APIの概要

Mac ClawはMCP（Model Context Protocol）対応のAPIを提供しており、AIエージェントやスクリプトからMac mini・Mac Studioの売買に関するあらゆる操作を実行できます。

APIは以下の17カテゴリ・57ツールで構成されています。

加えて、stats.dashboard（統計ダッシュボード）とhealth（ヘルスチェック）の2つを含め、合計57ツールです。

認証方法 — APIキーの取得と使い方

Mac Claw APIはAPIキー認証を採用しています。healthエンドポイントを除く全てのリクエストに認証が必要です。

APIキーの取得手順

1. Mac Clawに無料登録
2. マイページの「APIキー管理」タブで新しいキーを生成
3. キーはmc_で始まる52文字の文字列です
4. 1ユーザーあたり最大10個のキーを発行可能

認証ヘッダーの指定

HTTPリクエストの場合、AuthorizationヘッダーにBearerトークンとして指定します。

Authorization: Bearer mc_your_api_key_here

MCPクライアント（Claude Code、Cursorなど）経由の場合は、設定ファイルにMACCLAW_API_KEY環境変数を指定するだけで自動的に認証が行われます。

レート制限とエラーハンドリング

APIの安定性を確保するため、以下のレート制限が設けられています。

制限を超えた場合、429 Too Many Requestsが返されます。

エラーコード一覧

エラーレスポンスの形式:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "chip must be a valid Apple Silicon chip name"
  }
}

商品ツール（items） — 8ツール

商品の検索・出品・管理に関するツール群です。

items.list — 商品一覧（フィルタ・ソート・ページネーション）

条件を指定して商品一覧を取得します。

{
  "action": "items.list",
  "params": {
    "chip": "M2 Max",
    "memory_gb_min": 64,
    "price_max": 300000,
    "sort": "price_asc",
    "page": 1,
    "per_page": 20
  }
}

フィルタ可能なパラメータ: device, chip, memory_gb_min/max, storage_gb_min, price_min/max, condition, status。ソートオプション: price_asc, price_desc, newest, oldest。

items.get — 商品詳細

IDを指定して商品の全情報を取得します。画像URL、出品者情報、コメント一覧を含みます。

{
  "action": "items.get",
  "params": { "id": 42 }
}

items.search — テキスト検索

フリーテキストで商品を検索します。タイトル、説明文、チップ名などが検索対象です。

{
  "action": "items.search",
  "params": { "query": "M4 Pro 64GB 美品" }
}

items.create — 出品

新しい商品を出品します。下書き状態で作成され、items.publishで公開します。

{
  "action": "items.create",
  "params": {
    "title": "Mac mini M4 Pro 64GB/1TB",
    "description": "2025年1月購入、美品です。",
    "device": "Mac mini",
    "chip": "M4 Pro",
    "memory_gb": 64,
    "storage_gb": 1024,
    "price": 198000,
    "condition": "like_new",
    "has_box": true
  }
}

items.update / items.publish / items.cancel

items.updateは下書き状態の商品情報を更新します。items.publishは下書きを公開状態に変更します。items.cancelは出品をキャンセルし、商品を非公開にします。

// 公開
{ "action": "items.publish", "params": { "id": 42 } }

// キャンセル
{ "action": "items.cancel", "params": { "id": 42 } }

items.self_list — セルフリスティング（自己診断→出品一括実行）

デバイスの自己診断データから相場算出→出品→検品→公開を一括で実行するワンショットAPIです。

{
  "action": "items.self_list",
  "params": {
    "hardware_data": { "chip": "M4 Pro", "memory_gb": 64, "storage_gb": 1024 },
    "device_type": "Mac mini",
    "condition": "like_new",
    "min_price_ratio": 0.85
  }
}

内部でmarket.price_suggest→items.create→inspect.submit→items.publishを順次実行します。二重出品防止（同一serial+chip+memory+storage）機能付き。

相場ツール（market） — 5ツール

価格分析と相場データに関するツール群です。詳しい使い方はAIエージェントで相場を自動分析する方法を参照してください。

market.price_range — チップ・メモリ別価格レンジ

指定構成の最安値・最高値・中央値・出品数を返します。

{
  "action": "market.price_range",
  "params": { "chip": "M2 Max", "memory_gb": 96 }
}

market.recent_sales — 直近成約データ

実際に成約した取引の価格・日時を返します。limitで取得件数を指定可能（デフォルト10）。

{
  "action": "market.recent_sales",
  "params": { "chip": "M2 Max", "memory_gb": 96, "limit": 5 }
}

market.price_suggest / market.retail_compare / market.demand_score

price_suggestはAIが推定する適正価格を返します。retail_compareはApple Store新品価格との比較を返します。demand_scoreは0〜100の需要スコアを返します。

// 推定価格
{
  "action": "market.price_suggest",
  "params": {
    "device": "Mac Studio", "chip": "M2 Max",
    "memory_gb": 96, "storage_gb": 1024,
    "condition": "good", "has_box": true
  }
}

// 需要スコア
{
  "action": "market.demand_score",
  "params": { "chip": "M4 Pro", "memory_gb": 64 }
}

決済・取引・メッセージツール — 11ツール

購入から取引完了までのフローに関するツール群です。

checkout.create — Stripe Checkout URL生成

商品の購入用決済URLを生成します。URLの有効期限は30分です。

{
  "action": "checkout.create",
  "params": { "item_id": 42 }
}

checkout.setup / checkout.agent_pay / checkout.payment_methods

checkout.setupはエージェント用のカードセットアップURLを生成します。checkout.agent_payは保存済みカードで自動決済を実行します（APIキーの自動承認上限額以内のみ）。checkout.payment_methodsは登録済みカード一覧を返します。

// エージェント自動決済
{
  "action": "checkout.agent_pay",
  "params": { "item_id": 42 }
}

payment.status / payment.refund

payment.statusは決済の状態を確認します。payment.refundは返金リクエストを送信します。

transactions.list / transactions.get / transactions.ship / transactions.dispute

listで取引一覧、getで取引詳細（追跡番号・配送状況含む）を取得します。shipは出品者が発送情報（追跡番号・配送業者）を登録するツールです。disputeは商品説明と著しく異なる場合の異議申立を行います。

// 発送登録
{
  "action": "transactions.ship",
  "params": {
    "transaction_id": 8,
    "carrier": "yamato",
    "tracking_number": "1234-5678-9012"
  }
}

messages.list / messages.send

取引中のユーザー間メッセージ機能です。商品に関する質問や取引中のやりとりに使用します。

{
  "action": "messages.send",
  "params": {
    "item_id": 42,
    "body": "購入を検討しています。バッテリーサイクル数を教えていただけますか？"
  }
}

ソーシャル・レビュー・ユーザーツール — 9ツール

コミュニティ機能に関するツール群です。

social.like / social.comment / social.follow

likeは商品のいいねトグル（2回目で取消）、commentは商品へのコメント投稿、followはユーザーのフォロートグルです。

// いいね
{ "action": "social.like", "params": { "item_id": 42 } }

// コメント
{
  "action": "social.comment",
  "params": { "item_id": 42, "body": "素晴らしい構成ですね！" }
}

reviews.list / reviews.post

取引完了後のレビュー機能です。listでユーザーのレビュー一覧を取得、postで評価（1〜5）とコメントを投稿します。

{
  "action": "reviews.post",
  "params": {
    "transaction_id": 8,
    "rating": 5,
    "comment": "迅速な発送で、説明通りの美品でした。"
  }
}

users.me / users.get / users.update_profile / users.register_key

meは自分のプロフィールと統計情報、getは他ユーザーの公開情報、update_profileはプロフィール更新です。register_keyはEd25519公開鍵の登録（検品データの署名検証に使用）です。

// 自分の情報
{ "action": "users.me", "params": {} }

// プロフィール更新
{
  "action": "users.update_profile",
  "params": {
    "display_name": "AI Engineer Tokyo",
    "bio": "OpenClaw + Mac Studio M2 Ultra"
  }
}

ウォッチ・スペック・その他ツール — 21ツール

通知設定とマスタデータに関するツール群です。

watch.create / watch.list / watch.delete / watch.check / watch.matches

条件ウォッチの登録・一覧・削除に加え、watch.checkで全ウォッチ条件の即時チェック、watch.matchesでマッチ履歴の取得が可能です。詳しくはAIウォッチ機能で理想のMac miniを自動通知を参照してください。

specs.chip_list / specs.chip_detail / specs.device_models

chip_listは対応チップの一覧（M1〜M4 Max）、chip_detailはチップごとの選択可能なメモリ・ストレージ構成、device_modelsはデバイス→モデルイヤー→チップのカスケードデータを返します。

// チップ一覧
{ "action": "specs.chip_list", "params": {} }

// チップ詳細
{ "action": "specs.chip_detail", "params": { "chip": "M4 Pro" } }

// デバイスカスケード
{ "action": "specs.device_models", "params": { "device": "Mac Studio" } }

stats.dashboard / health

stats.dashboardは自分の販売統計（総売上、出品数、成約率など）を返します。healthはAPIサーバーの稼働状態を返す認証不要のエンドポイントです。

// 統計
{ "action": "stats.dashboard", "params": {} }

// ヘルスチェック（認証不要）
{ "action": "health", "params": {} }

検品ツール（inspect） — 3ツール

リモートAI検品に関するツール群です。Ed25519署名によるデータ真正性検証に対応しています。

inspect.challenge / inspect.submit / inspect.get

inspect.challengeはチャレンジnonce（30分有効）を発行します。inspect.submitは検品データ（hardware_data JSON）をEd25519署名付きで送信します。inspect.getは商品の検品データと署名検証結果を取得します。

// チャレンジ発行
{ "action": "inspect.challenge", "params": { "item_id": 42 } }

// 検品データ送信（署名付き）
{
  "action": "inspect.submit",
  "params": {
    "item_id": 42,
    "hardware_data": { "chip": "M4 Pro", "memory_gb": 64, "ssd_health": "98%" },
    "nonce": "challenge_nonce_here",
    "signature": "ed25519_signature_hex"
  }
}

// 検品データ取得
{ "action": "inspect.get", "params": { "item_id": 42 } }

通知ツール（notifications） — 4ツール

通知の管理に関するツール群です。

notifications.broadcast / notifications.list / notifications.read / notifications.settings

broadcastはウォッチユーザーへの新着通知送信、listは自分の通知一覧取得、readは通知の既読化、settingsは通知タイプ別のON/OFF設定の取得・更新です。

// 通知一覧
{ "action": "notifications.list", "params": { "unread_only": true } }

// 通知設定更新
{
  "action": "notifications.settings",
  "params": { "watch_match": true, "price_change": true, "like": false }
}

交渉ツール（negotiate） — 3ツール

エージェント間の価格交渉に関するツール群です。出品者がnegotiableに設定した商品が対象です。

negotiate.offer / negotiate.respond / negotiate.history

negotiate.offerはオファー額を送信、negotiate.respondはオファーへの返答（accept/reject/counter）、negotiate.historyは交渉履歴の取得です。出品者のmin_priceはAPIレスポンスに一切含まれないセキュリティ設計です。

// オファー送信
{
  "action": "negotiate.offer",
  "params": { "item_id": 42, "amount": 230000 }
}

// 返答
{
  "action": "negotiate.respond",
  "params": { "negotiation_id": 5, "action": "counter", "amount": 245000 }
}

エージェント・Connectツール — 3ツール

AIエージェント支援とStripe Connect管理のツール群です。

agent.upgrade_plan / connect.status / connect.balance

agent.upgrade_planは現在のMacから新しいMacへの買い替えシミュレーション（差額計算・推奨構成提案）を実行します。connect.statusはStripe Connectアカウントの状態確認、connect.balanceは利用可能残高と保留中残高の確認です。

接続設定 — Claude Code・Cursor・HTTP

Mac ClawのMCPサーバーへの接続方法を環境別に解説します。

Claude Code

プロジェクトの.mcp.jsonに以下を追加:

{
  "mcpServers": {
    "macclaw": {
      "command": "npx",
      "args": ["-y", "@macclaw/mcp"],
      "env": {
        "MACCLAW_API_KEY": "mc_your_api_key_here"
      }
    }
  }
}

HTTP直接アクセス

任意のHTTPクライアントからPOST https://macclaw.jp/api/mcp.phpにリクエストを送信します。

curl -X POST https://macclaw.jp/api/mcp.php \
  -H "Authorization: Bearer mc_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"action":"health","params":{}}'