convez.ai
MCP ServerIntegração & APIsIntermediário
Unlock-the-World

KEYVOX MCP Skills

Unlock-the-World/keyvox-mcp

Opere KEYVOX com comandos em linguagem natural via Claude

Ver no GitHub
BomPluginScore · de 0 a 100

Coleção de skills para Claude que permite operar o serviço de gerenciamento de acesso KEYVOX através de linguagem natural. Cobre 4 áreas operacionais: gestão de reservas, confirmação de check-in, suporte durante a estadia e planejamento de limpeza, eliminando a necessidade de decorar API keys ou comandos.

Instalação

$npx convez-ai Unlock-the-World/keyvox-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
87%
Último commit
há 5 meses
Versão
v0.1.3
Issues abertas
1
Contribuidores
1

Casos de uso

  • Gerenciar reservas, check-ins e cancelamentos em linguagem natural
  • Confirmar status de hóspedes e extrair dados de check-in não realizado
  • Responder a emergências como esquecimento de chaves e desbloqueios urgentes
  • Planejar limpeza diária e identificar quartos disponíveis para entrada imediata

Veredito

MCP server bem estruturado que abstrai a complexidade da API KEYVOX (70+ endpoints) através de skills reutilizáveis. Excelente para hospitais, hostels e property management, mas requer conta KEYVOX ativa e aprovação para OAuth2. Documentação em japonês pode ser barreira inicial para alguns usuários.

README

A tradução para o português deste README ainda está na fila.

KEYVOX MCP Skills

KEYVOX アクセス管理サービスを 自然言語で操作する ための Claude Skills コレクション。

予約管理・チェックイン確認・滞在中サポート・清掃計画の4業務領域をカバーします。

なぜ作ったか

KEYVOX API には 70近いエンドポイントがあり、業務と API の紐付けには熟練が必要です。 本スキル群を ~/.claude/skills/ に配置すると、Claude に以下のような自然言語で依頼するだけで業務が完結します。

  • 「今日の BCLtest の予約見せて」 → keyvox-reservation
  • 「101 号室のゲスト入った?」 → keyvox-checkin-status
  • 「ゲストが鍵忘れた」 → keyvox-onsite-support
  • 「今日の清掃対象は?」 → keyvox-housekeeping

API キー覚える必要なし、コマンド覚える必要なし、自然な日本語で。

スキル一覧

スキル名役割カバー業務SKILL.md
keyvox-reservation予約管理新規予約 / 確認 / 延長 / 変更 / キャンセルリンク
keyvox-checkin-statusチェックイン確認本日の状況 / 個別確認 / 未チェックイン抽出リンク
keyvox-onsite-support滞在中サポート鍵忘れ対応 / 緊急解錠 / 状況確認リンク
keyvox-housekeeping清掃計画本日の清掃対象 / 今すぐ入れる部屋 / 利用統計リンク

必要なもの

  • Claude.ai(Pro / Max / Team / Enterprise プラン)または Claude Code
  • KEYVOX アカウント(管理画面 BACS にログインできる)
  • KEYVOX MCP コネクタの OAuth2 クライアント ID
    • KEYVOX サポートポータル からチケットで発行依頼してください
    • 依頼時に必要な情報: redirect_uri = https://claude.ai/api/mcp/auth_callback

環境別の動作

  • Claude.ai (Web版) / Claude Desktop: 公式サポート対象。Claude Desktop は Claude.ai の Web 設定を共有するので同じコネクタ設定が使えます。
  • Claude Code (CLI/IDE): Claude.ai のコネクタは Claude Code には自動同期されません。Claude Code から使う場合は別途 .mcp.json 等で MCP server を設定する必要があります。

🚀 非エンジニア向けクイックスタート (Claude Desktop / Claude.ai)

ターミナル / git / コマンドライン操作なしで使う方法です。Claude.ai の Project 機能 にスキルを「知識」として読み込ませます。 Pro / Max / Team / Enterprise プランが必要 (Project 機能はFreeプラン非対応)。

ステップ 1: KEYVOX MCP コネクタを接続する (5〜10 分)

  1. KEYVOX サポートポータル で 「Claude 連携用の OAuth2 クライアント ID 発行希望」 とチケットを投げる
    • 伝える情報: redirect_uri = https://claude.ai/api/mcp/auth_callback
    • 返ってくるもの: クライアント ID (英数字の文字列)
  2. Claude Desktop または Claude.ai を開く → 設定 → コネクタ → カスタムコネクタを追加
    • 名前: keyvoxMCP
    • URL: https://eco.blockchainlock.io/mcp/sse
    • クライアント ID: ステップ 1 で取得した値
  3. 「連携」 → BACS にログイン → 同意画面で 対象組織を必ず明示的に選択 (デフォルトのままだと業務データを操作できません)

ステップ 2: このリポジトリを ZIP でダウンロード (1 分)

  1. このページ右上の 緑色の「Code」ボタン → 「Download ZIP」 をクリック Download ZIP
  2. ダウンロードした keyvox-mcp-main.zip を解凍
  3. フォルダの中に skills/ と references/ があることを確認

ステップ 3: Claude の Project にスキルを読み込ませる (5 分)

  1. Claude Desktop / Claude.ai のサイドバー → 「Projects」 → 「Create project」
  2. プロジェクト名: KEYVOX 業務 (任意)
  3. 「Project knowledge」 エリアに、解凍したフォルダから以下 9 ファイルをドラッグ&ドロップ:
    skills/keyvox-reservation-SKILL.md
    skills/keyvox-checkin-status-SKILL.md
    skills/keyvox-onsite-support-SKILL.md
    skills/keyvox-housekeeping-SKILL.md
    references/keyvox-mcp-setup.md
    references/keyvox-entities.md
    references/keyvox-tool-map.md
    references/keyvox-id-resolution.md
    references/keyvox-enums.md
    
  4. 「Project instructions」 欄に以下をコピペ:
    あなたは KEYVOX アクセス管理サービスの業務アシスタントです。
    Project knowledge にアップロードされている 4 つの SKILL.md と
    5 つの references/*.md を必ず参照してください。
    
    - ユーザーの発話から該当スキル (reservation / checkin-status /
      onsite-support / housekeeping) を判定し、対応する SKILL.md の
      手順に従って MCP ツール (keyvoxMCP コネクタ) を呼び出す
    - 不可逆操作 (createReservation, cancelReservation, unlock,
      createLockPin 等) は必ずユーザーの最終承認を取ってから実行
    - 401 / E2003 エラー時は keyvox-mcp-setup.md の「定型応答」を
      そのままユーザーに出力 (要約・言い換え禁止)
    
  5. 保存 して、このプロジェクト内で新しいチャットを開始

ステップ 4: 動作確認 (1 分)

プロジェクト内のチャットで以下を試す:

今日の予約見せて

→ Claude が keyvoxMCP コネクタの listReservations を呼んで、本日の予約一覧を返せば成功 🎉

❓ うまく動かないとき

症状対処
Claude が「ツールが見つからない」と言うコネクタが接続済みか確認 (設定 → コネクタ → keyvoxMCP が「接続済み」になっているか)
「権限がない」「データがない」と言われる対象組織の選択ミス。コネクタを一度「切断」して再連携、同意画面で正しい組織を選ぶ
Project knowledge にアップロードできないファイル数 / サイズ上限の可能性。Free プランでは Project 自体が使えないので Pro 以上か確認
その他Discord または KEYVOX サポート へ

💡 アップデートの取り込み方

このリポジトリが更新されたら、再度 ZIP をダウンロードして Project knowledge のファイルを上書きしてください。手作業ですが「git の使い方を覚える」より圧倒的に早いです。


💬 ChatGPT で使う場合

ChatGPT では Claude Skills としての自動発火機構は使えませんが、Project files と Project instructions を使って同等の業務スキルとして利用できます。

Claude 版との主な違い

Claude.ai (Projects)ChatGPT (Projects)
ナレッジの置き場所Project knowledgeProject files
指示文の置き場所Project instructionsProject instructions
スキル発火SKILL.md の description で 自動マッチングProject instructions に書いた 明示的ルーティング
MCP 接続カスタムコネクタ keyvoxMCP を Claude.ai 側で設定ChatGPT 側で別途 MCP / コネクタ設定が必要 (Pro / Business / Enterprise などプラン要件あり)

重要: Claude のように description 経由で勝手にスキルが発火するわけではないため、ChatGPT では Project instructions に 「どの発話で、どの SKILL.md を読むか」を明示的に書く 必要があります。

ステップ 1: KEYVOX MCP を ChatGPT に接続

ChatGPT 側の MCP / コネクタ設定手順に従って https://eco.blockchainlock.io/mcp/sse を接続してください。OAuth2 クライアント ID の発行依頼方法は Claude 版と同じく KEYVOX サポートポータル 経由です (申請時は ChatGPT 用の redirect_uri を必ず伝えてください)。

ステップ 2: Project files に 9 ファイルをアップロード

解凍した ZIP から以下を ChatGPT の Project files にドラッグ&ドロップ:

skills/keyvox-reservation-SKILL.md
skills/keyvox-checkin-status-SKILL.md
skills/keyvox-onsite-support-SKILL.md
skills/keyvox-housekeeping-SKILL.md
references/keyvox-mcp-setup.md
references/keyvox-entities.md
references/keyvox-tool-map.md
references/keyvox-id-resolution.md
references/keyvox-enums.md

ステップ 3: Project instructions に以下をコピペ

あなたは KEYVOX アクセス管理サービスの業務アシスタントです。

Project files にアップロードされている 4つの SKILL.md と 5つの references/*.md を必ず参照してください。

ユーザーの発話から該当業務を判定してください。

- 予約管理: keyvox-reservation-SKILL.md
- チェックイン確認: keyvox-checkin-status-SKILL.md
- 滞在中サポート: keyvox-onsite-support-SKILL.md
- 清掃計画: keyvox-housekeeping-SKILL.md

該当する SKILL.md の手順に従い、接続済みの KEYVOX MCP ツールを呼び出してください。

不可逆操作、特に createReservation、cancelReservation、unlock、createLockPin、delete、revoke、update 系の操作は、必ずユーザーに内容を確認し、明示的な最終承認を得てから実行してください。

401、権限不足、対象組織違い、E2003 などのエラーが出た場合は、keyvox-mcp-setup.md の定型応答に従って案内してください。

ユーザーには API 名や内部 ID をなるべく見せず、自然な業務言語で応答してください。

Claude 版の Project instructions と比べて、どの発話でどの SKILL.md を読むかの対応表 と 「内部 ID を見せず自然な業務言語で返す」指示 を明示的に入れているのがポイントです。ChatGPT は自動発火しない分、ルーティングを文章で誘導する必要があります。

ステップ 4: 動作確認

プロジェクト内のチャットで 今日の予約見せて などを試し、KEYVOX MCP ツール (listReservations 等) が呼ばれて本日の予約が返れば成功です。


セットアップ手順 (エンジニア向け)

Step 1: KEYVOX MCP コネクタを Claude.ai に追加

  1. KEYVOX サポートポータル で OAuth2 クライアント ID を申請して取得
  2. https://claude.ai/customize/connectors を開く
  3. 右上 「+」 → カスタムコネクタ追加:
    • 名前: keyvoxMCP (任意。本READMEと各SKILL.md ではこの名前で参照しているので、別名にする場合は読み替えてください)
    • URL: https://eco.blockchainlock.io/mcp/sse
    • クライアント ID: Step 1 で取得した値
  4. 「連携」 ボタンで OAuth 認可フロー → BACS ログイン → 同意
    • ⚠️ 対象組織の選択を間違えないこと。デフォルトのままだと認証は通っても E2003 権限不足 で API が失敗します
  5. 接続確認: 「keyvoxMCP に接続しました」のトーストが出れば OK

Step 2: スキルを配置

Claude Code は ~/.claude/skills/<skill-name>/SKILL.md という構造を期待するので、本リポのフラットな skills/keyvox-*-SKILL.md から 個別フォルダ + SKILL.md にマッピングする必要があります。

A. シンボリックリンク方式(推奨・編集が即反映)

git clone https://github.com/Unlock-the-World/keyvox-mcp.git ~/keyvox-mcp

for skill in reservation checkin-status onsite-support housekeeping; do
  mkdir -p ~/.claude/skills/keyvox-$skill
  ln -sf ~/keyvox-mcp/skills/keyvox-$skill-SKILL.md \
         ~/.claude/skills/keyvox-$skill/SKILL.md
done

B. 単純コピー方式

git clone https://github.com/Unlock-the-World/keyvox-mcp.git

for skill in reservation checkin-status onsite-support housekeeping; do
  mkdir -p ~/.claude/skills/keyvox-$skill
  cp ./keyvox-mcp/skills/keyvox-$skill-SKILL.md \
     ~/.claude/skills/keyvox-$skill/SKILL.md
done

💡 なぜマッピングが必要か: 本リポは Claude Project (knowledge アップロード時にファイル名衝突を避ける必要) と Claude Code (フォルダ + SKILL.md 規約) の両方をサポートするため、内部ではフラットな keyvox-*-SKILL.md 形式で保持しています。Claude Code への配置時のみ、上記スクリプトで規約形式に展開します。

Step 3: 動作確認

Claude.ai または Claude Code を 新規セッションで起動 し、以下のような発話を試す:

KEYVOX のテストして

keyvox-reservation 等のスキルが発火し、place_list を叩いて物件情報を返せば成功。

利用例

以下の例に登場する物件名 (BCLtest)、ゲスト名 (山田 / 佐藤 / 鈴木)、予約 ID、PIN コード、電話番号などは すべて架空のサンプル です。実際の挙動はあなたの環境のデータに置き換わります。

例1: 朝のルーチン確認

You: 今日の BCLtest 予約見せて

Claude:
[keyvox-reservation 発火]
本日 (05/28) BCLtest 予約一覧 (3件)
| # | 時刻        | 部屋 | ゲスト | 状態 |
|---|-------------|------|--------|------|
| 1 | 14:00-17:00 | 101  | 山田   | 確定 |
| 2 | 15:00-18:00 | 102  | 佐藤   | 確定 |
| 3 | 10:00-13:00 | 103  | 鈴木   | 確定 |

例2: チェックイン状況確認

You: 101 号室の山田さん入った?

Claude:
[keyvox-checkin-status 発火]
山田太郎さん (予約 ABCDEFGHI / 101 号室 14:00-17:00)
状態: ✅ チェックイン済
- 初回解錠: 14:05 (QR 経由)
- 直近解錠: 16:42
- 解錠回数: 3 回

例3: 鍵忘れ対応

You: 102 号室の佐藤さんが鍵を紛失したらしい

Claude:
[keyvox-onsite-support 発火]
状況確認します:
- 佐藤さんの既存 PIN: 836241 (有効期間 15:00-18:00)
このPINを SMS / LINE で再送するのが最速です。
それでも開かない場合、新規一時 PIN 発行か、リモート解錠を提案できます。

新規 PIN を発行しますか? (Y/N)

例4: 清掃計画

You: 今日の清掃対象は?

Claude:
[keyvox-housekeeping 発火]
本日の清掃対象 (BCLtest)
| # | 部屋 | チェックアウト | 次チェックイン | 清掃可能時間枠 |
|---|------|----------------|----------------|----------------|
| 1 | 101  | 11:00          | 14:00 (今日)   | 3 時間         |
| 2 | 102  | 12:00          | 翌日 10:00     | 22 時間        |

合計 2 件 (うちノーショウ除外 1 件)

共通リファレンス

スキル群は以下のドキュメントを参照する設計です。

ファイル内容
references/keyvox-mcp-setup.mdコネクタ環境前提・再認証手順・典型エラー対処 (全スキル共通)
references/keyvox-entities.md7 リソース(place / unit / lock / pin / card / user / reservation)の仕様 + ER 図
references/keyvox-tool-map.md業務シナリオ → MCP ツール対応表
references/keyvox-id-resolution.md自然言語 → ID 解決パターン集
references/keyvox-enums.mdorderStateCode 等の enum 値辞書

トラブルシューティング

症状対処
スキルが発火しないセッション再起動。SKILL.md の description が業務文脈に合っているか確認
401 Unauthorizedコネクタの OAuth トークン期限切れ。references/keyvox-mcp-setup.md の再認証手順を参照
E2003 権限不足OAuth 同意時の「対象組織」が間違っている。再認証して正しい組織を選択
E0043 データが存在しませんplaceId / orderId の typo or 他組織の ID
Failed to start OAuth flow: ... DCRClaude Code の自動 OAuth は KEYVOX 非対応。Claude.ai 経由で接続すること

アーキテクチャ

[あなた]
   ↓ 自然言語
[Claude.ai / Claude Code]
   ↓ (1) Skills 発火 (description で判別)
   ↓ (2) スキル内手順に従い MCP ツールを選択
[KEYVOX MCP コネクタ (eco.blockchainlock.io)]
   ↓ OAuth2 認可済みリクエスト
[KEYVOX API]
   ↓ 業務データ取得・更新
[ロック・PIN・予約システム]

スキル本体は MCP ツールの応用レシピ。MCP ツール直叩きでも同じことはできますが、業務手順を覚えなくていい・自然言語で済むのが利点です。

ライセンス

MIT — Copyright © 2026 Blockchain Lock Inc. / KEYVOX Contributors

Contributing

Issue / PR 歓迎です。特に以下のシナリオでの実利用フィードバックを募集中:

  • 本番物理ロックでの unlock 動作確認
  • バックトゥバック予約での清掃計画運用
  • マルチ place(複数物件)運営での発火精度

コントリビュート手順の詳細は CONTRIBUTING.md を参照してください。すべての参加者は 行動規範 (Code of Conduct) に従ってください。

セキュリティ

物理スマートロックを操作する性質上、脆弱性報告は最優先で扱います。GitHub Issues に公開で投稿せず、SECURITY.md の手順で非公開報告してください。

関連リンク

Ver o original no GitHub

Bom para

Relacionados