--- title: "録音を AI が使えるデータに変える：ScribeSTT の文字起こし、NAS 連携、MCP/CLI" description: "4 つのシナリオ：メディアファイルをアップロードして文字起こしを取得する、NAS を接続して一括文字起こしを行う、AI エージェントに MCP でサービスを探索させる、CLI で文字起こしをスクリプトやスケジュールに組み込む" canonical_url: "https://docs.ardge.com/ja/knowledge/scribestt/mcp-cli-integration" --- # 録音を AI が使えるデータに変える：ScribeSTT の文字起こし、NAS 連携、MCP/CLI > 4 つのシナリオ：メディアファイルをアップロードして文字起こしを取得する、NAS を接続して一括文字起こしを行う、AI エージェントに MCP でサービスを探索させる、CLI で文字起こしをスクリプトやスケジュールに組み込む ## 概要 ScribeSTT は ARX プラットフォーム上の音声・映像文字起こしアプリケーションです。メディアファイル内の発話内容を、タイムスタンプ付きの文字起こしに変換します。 ナレッジベースはテキストで構成されます。録音をタイムスタンプ付きの文字起こしに変えることが、AI が音声や映像を横断して検索できるようになる前提です。 本記事では 4 つのシナリオを扱います。互いに独立しているため、必要なものだけ読んでください。 - **シナリオ 1 · アップロードしたファイルを文字起こしする**：メディアファイルを ScribeSTT に送り、文字起こしを受け取る - **シナリオ 2 · NAS を接続する**：既存のファイルサーバーを接続し、そこにあるファイルを一括で文字起こしする - **シナリオ 3 · MCP 連携**：AI エージェント自身に ScribeSTT へ接続させ、音声の送信先を探索させる - **シナリオ 4 · CLI 連携**：文字起こしをスクリプト、スケジュール、CI パイプラインに組み込む ## 対象バージョン - ARX OS 1.0 以降 - ScribeSTT 1.0 以降 ## 事前準備 次の 2 点を確認してください。 - App Market から ScribeSTT をインストールしていること - お使いのアカウントに ScribeSTT のアクセス権があり、デスクトップにアプリケーションが表示されること --- ## シナリオ 1. アップロードしたファイルを文字起こしして結果を取得する 手元に少数のファイルがあり、まず文字起こしの品質を確認したい場合に適したシナリオです。すべての操作は **Transcriptions** ページで完結し、設定は不要です。 ### 1. ファイルをアップロードする 1. 左側ナビゲーションの **Workspace** グループから **Transcriptions** ページへ移動します 2. **New** をクリックします 3. 文字起こしするファイルを選択するか、ドロップ領域へドラッグします 4. メディアで話されている言語を設定し、文字起こしの精度を高めます 5. **Glossary** を設定して固有名詞の認識を助けます。これも精度の向上につながります 6. **Create** をクリックして開始します > **対応形式**：mp3、wav、ogg、flac、wma、opus、mp4、webm、avi、flv、wmv、3gp > **1 回のアップロードの上限**：20 ファイル、1 ファイルあたり 1 GB ### 2. 文字起こしを確認する 1. **Transcriptions** ページで、確認したいファイルの行をクリックします 2. ダイアログが開き、srt・txt・json の 3 形式が提供されます ### 3. 文字起こしをダウンロードする 1. **Transcriptions** ページでダウンロードするファイルを選択します 2. **Download** のドロップダウンボタンをクリックし、必要な形式を選びます --- ## シナリオ 2. NAS を接続し、既存の録音を一括で文字起こしする 社内の録音がすでに NAS 上にある場合、1 つずつアップロードする必要はありません。ScribeSTT は SMB で NAS に接続してファイルを直接読み取り、文字起こしを指定した別のフォルダーへ書き出します。元のデータは変更されず、同時にナレッジベースの元テキストが用意されます。 ### 1. NAS 接続を設定する 1. 左側ナビゲーションの **Workspace** グループから **Remote data sources** ページへ移動します 2. **New** をクリックして **New data source** ダイアログを開きます 3. 接続名、NAS の IP アドレス、ユーザー名とパスワードを入力します 4. **Test connection** をクリックし、**Shared folder** のドロップダウンからフォルダーを選びます ### 2. 文字起こしタスクを作成する 1. **Tasks** ページへ移動します 2. **New** をクリックします 3. タスク名、ソースフォルダー、ターゲットフォルダー、出力形式、走査の深さを設定します 各項目の意味は次のとおりです。 - **ソースフォルダー**：このタスクが処理する録音の所在 - **ターゲットフォルダー**：生成された文字起こしの保存先 - **走査の深さ**：フォルダーを何階層まで走査するか ### 3. タスクを実行する 1. **Tasks** ページへ移動します 2. 実行するタスクの行で **Run** をクリックします 3. そのタスク行の Last Result が Completed になるまで待ちます --- ## シナリオ 3. AI エージェントが MCP 経由で ScribeSTT に接続する 最初の 2 つのシナリオは、いずれも人が Web インターフェースで操作するものです。AI エージェント（Claude Code、Cursor、あるいは自社開発のもの）自身に ScribeSTT へ接続させるには、ScribeSTT の **HTTP MCP** インターフェースを利用します。 現時点で MCP が担う範囲を整理しておきます。MCP は、エージェントが接続を確認し、音声の送信先を知るための経路です。文字起こしそのものは REST API または CLI（シナリオ 4）で実行します。 接続が完了すると、エージェントは次の 2 つのツールを呼び出せます。
ツール 用途 権限レベル データソース制限
arxstt_get_system_version サーバーのバージョン、git SHA、ビルド日時を返します。接続確認に使用します レベル不問 —
arxstt_list_capabilities この資格情報で呼び出せるツールを一覧表示します。アップロードが許可されている場合は音声アップロード用のエンドポイントも返します。セッションごとに最初に呼び出してください レベル不問 —
> ⚠️ **MCP は既定で無効です** > このエンドポイントは新たな攻撃面となるため、デプロイごとに明示的に有効化する必要があります。`mcp.enabled` 設定または `ARXSTT_MCP_ENABLED` 環境変数で有効にしてください。 > ⚠️ **音声が MCP を通ることはありません** > MCP のリクエストボディは 256 KB が上限で、この枠はツール呼び出しの引数のみを対象とします。音声は別の REST エンドポイントを経由するため、エージェントを動かす環境は HTTP リクエストを送信できる必要があります（`curl`、Python の `requests`、ワークフローエンジンの HTTP ノードなど）。 > コードの実行も HTTP リクエストの送信もできないチャット専用のインターフェースでは、音声を送信できません。 ### 1. アクセス用の PAT を作成する MCP 接続は **PAT（パーソナルアクセストークン）** で認証します。PAT はスーパー管理者が Web インターフェースで発行します。 1. ScribeSTT を開き、ユーザーページへ移動します 2. 権限を付与するユーザーの行の操作列で「Manage Personal Access Token」をクリックします 3. 「Personal Access Tokens」ダイアログで「Create」ボタンをクリックします 4. 「Create Personal Access Token」ダイアログで、トークン名、操作権限、アクセスできるフォルダー、有効期限を設定します 5. 生成されたトークンを取得します > ⚠️ **トークンはすぐに保管してください** > トークンが生成されたら、エージェントが起動時に読み取れる場所へ保管してください。紛失した場合は再作成するしかありません。 PAT の作成では 2 種類のスコープを決めます。 - **操作スコープ**：`read_only` は照会のみ、`default` は作成・更新・キャンセル・リトライ・トリガーを追加、`destructive` は削除を追加します。各ツールは受け入れるレベルを自身で宣言します - **データアクセススコープ**：この PAT が到達できるデータソースです。空のままにすると**すべて拒否**されます ### 2. AI エージェントで MCP サーバーを設定する 次の接続情報をエージェントの MCP 設定に記述します。
項目 値
Endpoint https:///mcp —— 既定のパスで、 mcp.endpoint 設定または ARXSTT_MCP_ENDPOINT 環境変数で変更できます
Transport Streamable HTTP
認証 Authorization: Bearer （PAT は arxstt_pat_… の形式です）
リクエストごとの上限 256 KB。 mcp.maxRequestBodyBytes または ARXSTT_MCP_MAXREQUESTBODYBYTES で設定します。この枠が対象とするのはツール呼び出しの引数で、音声はこのエンドポイントを通りません
> 💡 ** の調べ方** > ARX のデスクトップで ScribeSTT のアイコンを右クリックし、新しいタブで開いてから、アドレスバーのドメインをコピーします。 Claude Code の場合、設定は次のようになります。 ```json { "mcpServers": { "ScribeSTT": { "type": "http", "url": "https:///mcp", "headers": { "Authorization": "Bearer " } } } } ``` ### 3. 音声をアップロードして文字起こしを開始する まず `arxstt_list_capabilities` を呼び出します。PAT のレベルが `default` 以上であれば、レスポンスに `uploadEndpoint` の記述が含まれ、送信先のパスと受け付けるフィールドが示されます。パスはここから読み取り、ハードコードしないでください。`read_only` のみの PAT では、アップロードエンドポイントは返されません。
項目 値
アップロードエンドポイント POST /api/v1/transcriptions/upload
認証 MCP 接続と同じ Bearer PAT
Content type multipart/form-data
ファイルサイズ上限 既定は 1 GiB。 upload.maxFileSizeBytes または ARXSTT_UPLOAD_MAXFILESIZEBYTES で設定します
フォームフィールドは `audioFile`（必須）と、任意の `language`（`zh`、`en`、`ja`、`ko`。省略すると自動判定）、`glossaryId`、`outputFormats`（`txt`、`srt`、`json`。省略すると 3 種類すべてを生成）です。 アップロードの例： ```bash curl -X POST https:///api/v1/transcriptions/upload \ -H "Authorization: Bearer " \ -F "audioFile=@meeting.mp3" \ -F "language=en" ``` レスポンスでは、その文字起こしの `id` が返されます。 > ⚠️ **文字起こしを返す MCP ツールはありません** > 上記の 2 つのツールが担うのは接続確認と情報取得のみです。アップロードが受理されたあとは、REST API または CLI で状態を追跡し、テキストを取得してください（シナリオ 4 を参照）。 --- ## シナリオ 4. AI エージェントが CLI 経由で ScribeSTT で音声を文字起こしする CLI は単一の実行ファイルで、スクリプト、スケジュールタスク、CI パイプライン、あるいは shell 権限を持つエージェントが直接コマンドを発行する用途に適しています。自動化のために設計されており、すべてのコマンドが `--json` 出力に対応し、エラーを終了コードで分類するため、プログラム側で次の動作を判断できます。 コマンド一覧：
グループ コマンド
認証 auth login 、 auth status 、 auth logout
文字起こし transcription upload 、 transcription get 、 transcription list 、 transcription output 、 transcription cancel 、 transcription retry 、 transcription delete
バッチタスク task create 、 task get 、 task list 、 task trigger 、 task delete
バッチ実行 run get 、 run list 、 run cancel
データソース datasource list 、 datasource get 、 datasource entries
用語集 glossary create 、 glossary get 、 glossary list 、 glossary delete
すべてのコマンドに共通するフラグ：`--server `、`--token `、`--config `、`--json`、`--fields <フィールド一覧>` > 💡 **各コマンドが自身を説明します**`arx-stt --help --json` はコマンドツリー全体を、`arx-stt transcription get --help --json` は単一コマンドの引数・フラグ・出力フィールドを出力します。エージェントは外部の説明に頼らず、自分で調べられます。 ### 1. CLI をインストールする 実行ファイルは ScribeSTT サーバー自身が配布するため、外部のパッケージレジストリは不要です。次のコマンドは `~/.local/bin` にインストールし、sudo を必要としません。 ```bash export ARXSTT_SERVER="https://" OS=$(uname -s | tr '[:upper:]' '[:lower:]') ARCH=$(uname -m); [ "$ARCH" = "x86_64" ] && ARCH="amd64"; [ "$ARCH" = "aarch64" ] && ARCH="arm64" mkdir -p "$HOME/.local/bin" curl -fSL -o "$HOME/.local/bin/arx-stt" \ "${ARXSTT_SERVER}/api/v1/cli/download?os=${OS}&arch=${ARCH}" chmod +x "$HOME/.local/bin/arx-stt" export PATH="$HOME/.local/bin:$PATH" ``` ### 2. ログインしてアクセス権を得る CLI は PAT で認証します。作成方法はシナリオ 3 と同じです（[アクセス用の PAT を作成する](#1-%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E7%94%A8%E3%81%AE-pat-%E3%82%92%E4%BD%9C%E6%88%90%E3%81%99%E3%82%8B)を参照）。 ```bash # Store the PAT (this non-interactive form is the one to use for automation) arx-stt auth login --server https:// --token # Or pipe it in, to keep the token out of your command history echo | arx-stt auth login --server https:// # Or just set the environment variable, writing nothing to disk export ARXSTT_TOKEN= ``` 続いて確認します。 ```bash arx-stt auth status --json # shows where the PAT came from, and checks it against the server ``` - 資格情報は次の順に参照されます：`--token` フラグ、次に `ARXSTT_TOKEN`、最後に設定ファイル - 設定ファイルは `~/.arx-stt/config.yaml`（パーミッション 0600）にあります。`--config` または `ARXSTT_CONFIG` で別のパスを指定できます - ログインに成功したあとは、以降のコマンドで `--server` は不要です - `arx-stt auth logout` はローカルに保存された PAT を消すだけで、サーバー側で失効させるわけでは**ありません** ### 3. 単一ファイルを文字起こしする ```bash # upload, wait for the transcription to reach a terminal state, then fetch the text id=$(arx-stt transcription upload meeting.mp3 --json | jq -r .id) arx-stt transcription get "$id" --json --wait --timeout 30m arx-stt transcription output "$id" --format txt > transcript.txt # or fused into one call, which prints the terminal-state transcription arx-stt transcription upload meeting.mp3 --wait --json ``` `transcription upload` は `--language`、`--glossary`、`--formats` も受け付けます。`transcription output` は既定で標準出力に書き出し、`--format txt|srt|json` または `--out FILE` を指定できます。 `--wait` を付けると、終了コードが結果を示します。`0` は完了またはスキップ、`5` は失敗またはキャンセル、`4` はタイムアウトです。タイムアウトしてもサーバー側の処理は続くため、`transcription get --wait` をもう一度実行すれば監視を再開できます。 レコードのキャンセル・リトライ・削除はそれぞれ `transcription cancel `、`transcription retry `、`transcription delete ` です。リトライは失敗およびキャンセルされたレコードが対象で、スキップされたレコードには適用できません。削除には `destructive` レベルの PAT が必要です。 ### 4. 一括文字起こし 一括処理は 3 つのオブジェクトで構成されます。**データソース**（ファイルの所在）、**タスク**（静的な設定）、**実行**（1 回の実際の処理）です。 #### データソースを選ぶ ```bash arx-stt datasource list --scheme smb --json arx-stt datasource entries --path recordings/ --json ``` `datasource entries` でフォルダーを閲覧し、ソースパスを選びます。ローカルファイルシステムのデータソースはシステムが管理しており、一覧には表示されません。 #### タスクを作成する ```bash arx-stt task create --name nightly \ --source-datasource --source-path recordings/ \ --target-datasource --target-path transcripts/ \ --output-format txt --scan-depth 2 --json ``` - `--scan-depth`：フォルダーを何階層まで走査するか - `--glossary`：タスク内のすべてのファイルに用語集を適用する #### 実行と監視 ```bash run=$(arx-stt task trigger --json | jq -r .runId) arx-stt run get "$run" --json --wait arx-stt run list --task --status failed --json ``` `task trigger` はソースフォルダーを走査する実行を作成し、その `runId` を出力します。`run get` に `--wait` を付けた場合、終了コード `0` は完了、`5` は部分完了・失敗・キャンセルを意味します。`run cancel ` は実行をキャンセルし、その配下でまだ処理中の文字起こしにも波及します。 タスクの削除には `destructive` レベルの PAT が必要で、その実行が進行中のあいだは削除できません。 #### 用語集 ```bash arx-stt glossary create --name product-names \ --term "scribe stt=ScribeSTT" --term "ardge=ARDGE" --json ``` `--term` はそれぞれ、認識が出しやすい誤った形を、文字起こしに現れてほしい正しい形へ対応づけます。既存の用語集の語句を編集するのは Web インターフェースの作業で、CLI は作成・参照・削除を担います。 ### 5. 自動化での注意点 エラーは終了コードで分類されるため、スクリプトはエラーメッセージを解析せずコードで分岐できます。
終了コード 意味 対応
0 成功 —
1 クライアントエラー（入力の誤り、対象が見つからない） 入力を修正する。リトライしない
2 認証または認可の失敗 自動でリトライしないこと。 PAT が無効か、スコープが拒否されました。PAT を差し替えてください
3 サーバーエラー（5xx） 時間を置いてリトライする
4 ネットワークまたは一時的なエラー（ポーリングのタイムアウトを含む） バックオフを入れてリトライする
5 処理が失敗・キャンセル・部分完了の終了状態に到達した JSON 出力の errorCode を確認する
130 Ctrl-C による中断 ユーザーによる中止
JSON 形式のエラーは `{"errors":{"code":…,"message":…,"hint":…}}` の形で標準出力に出力されます。 エージェントが CLI を使う場合は、次の点を守ってください。 - **必ず --json を付ける**：表形式の出力は人間向けで、プログラムが確実に解析することはできません - **--fields で出力を絞る**：たとえば `--fields id,status`。必要なフィールドだけを取得すればコンテキストを節約できます - **--dry-run はありません**：`create`、`trigger`、`delete` は即座に反映されます。変更や削除の前に `get ` で対象を確認してください - **メッセージ本文ではなく終了コードで分岐する**：コードは安定した契約ですが、文面はそうではありません ## Sitemap See the full [sitemap](https://docs.ardge.com/sitemap.md) for all pages.