Liveability MCP API リファレンス

日本語住所の生活利便性スコアリング API・MCP サーバー — v1.4 開発者ドキュメント

1. APIキー取得

下のボタンからメールアドレスを登録するだけで、即時に APIキー (lvb_ プレフィックス) が発行されます。

APIキーを発行する

発行された平文キーは1度きり表示されます。表示後は /my/keys ダッシュボードで管理してください。

2. 認証

APIキーは X-API-Key ヘッダーまたは Authorization: Bearer ヘッダーのいずれでも認証できます。

X-API-Key 形式

curl -X POST https://liveability.jp/evaluate \
  -H 'X-API-Key: lvb_AbCdEf...' \
  -H 'Content-Type: application/json' \
  -d '{"address":"兵庫県洲本市本町3丁目1-18"}'

Authorization Bearer 形式

curl -X POST https://liveability.jp/evaluate \
  -H 'Authorization: Bearer lvb_AbCdEf...' \
  -H 'Content-Type: application/json' \
  -d '{"address":"兵庫県洲本市本町3丁目1-18"}'

サインアップ → 評価までのフル例 (-i でレート制限ヘッダーを確認)

# 1. メアド登録 → 平文キーを1度だけ受け取る
curl -i -X POST https://liveability.jp/signup \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com"}'
# → 201 Created
# {
#   "key": "lvb_AbCdEf...",          ← 必ず保存してください (1度のみ表示)
#   "key_prefix": "lvb_AbCdEf12",
#   "rate_limit_per_hour": 1000,
#   "instructions": { "header_x_api_key": "X-API-Key: lvb_AbCdEf..." }
# }

# 2. キーで評価 (-i でレート制限ヘッダーも確認)
curl -i -X POST https://liveability.jp/evaluate \
  -H 'X-API-Key: lvb_xxx' \
  -H 'Content-Type: application/json' \
  -d '{"address":"大阪市北区梅田1丁目"}'
# → 200 OK
# X-RateLimit-Limit: 1000
# X-RateLimit-Remaining: 999
# X-RateLimit-Reset: 1746642000
# { "score": ..., "highlights": [...], "confidence": "high", ... }

3. レート制限

各APIキーは 1時間あたりデフォルト1000リクエスト の スライディングウィンドウ制限が適用されます。マスターキー（内部利用）は対象外です。

ヘッダー意味
X-RateLimit-Limit1時間あたりの上限リクエスト数（例: 1000）
X-RateLimit-Remaining現在のウィンドウで残っている呼び出し可能数
X-RateLimit-Reset次のウィンドウ開始時刻（Unix epoch 秒、GitHub 方式）
Retry-After429 時のみ。再試行までの秒数（delta-seconds, RFC 9110）

429 レスポンス例

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1746642000
Retry-After: 47

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. You can make 1000 requests per hour. Retry after 47 seconds.",
  "retry_after": 47
}

4. エラーコード一覧

HTTPerror対処
401unauthorizedAPIキーが未指定・無効・revoke 済み。/my/keys で再発行してください。
409email_already_registered 等サインアップ衝突。既存メアドでは /my/login へ。
429rate_limit_exceededRetry-After 秒待ってから再送してください。
500server_errorサーバ起因のエラー。指数バックオフで再試行してください。

5. Claude Desktop 設定

下記を ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) に貼り付けてください。

重要: mcp-remote@0.1.38 のバージョンは固定です。 v11.x は OAuth が必須となり API キー認証では動作しません。

{
  "mcpServers": {
    "liveability": {
      "command": "npx",
      "args": [
        "mcp-remote@0.1.38",
        "https://liveability.jp/mcp/sse",
        "--transport",
        "sse-only",
        "--header",
        "X-API-Key:{MCP_API_KEY{'}'}"
      ],
      "env": {
        "MCP_API_KEY": "lvb_your_key_from_my_keys_dashboard"
      }
    }
  }
}

注意: X-API-Key:${MCP_API_KEY} はコロンの後にスペースを入れない形式です（Windows 互換）。

6. Cursor 設定

プロジェクト直下の .cursor/mcp.json またはユーザーグローバル ~/.cursor/mcp.json に貼り付けてください。 Cursor も内部で mcp-remote を起動するため、Claude Desktop と同じ設定形式です。

{
  "mcpServers": {
    "liveability": {
      "command": "npx",
      "args": [
        "mcp-remote@0.1.38",
        "https://liveability.jp/mcp/sse",
        "--transport",
        "sse-only",
        "--header",
        "X-API-Key:{MCP_API_KEY{'}'}"
      ],
      "env": {
        "MCP_API_KEY": "lvb_your_key_from_my_keys_dashboard"
      }
    }
  }
}

7. 今後の予定