---
title: "把錄音變成 AI 能用的資料：ScribeSTT 語音轉錄、NAS 串接與 MCP／CLI 整合"
description: "四個情境：上傳影音檔案取得逐字稿、串接 NAS 進行批次轉錄、讓 AI Agent 透過 MCP 探詢服務，以及用 CLI 把轉錄接進腳本與排程"
canonical_url: "https://docs.ardge.com/zh-tw/knowledge/scribestt/mcp-cli-integration"
---
# 把錄音變成 AI 能用的資料：ScribeSTT 語音轉錄、NAS 串接與 MCP／CLI 整合

> 四個情境：上傳影音檔案取得逐字稿、串接 NAS 進行批次轉錄、讓 AI Agent 透過 MCP 探詢服務，以及用 CLI 把轉錄接進腳本與排程

## Overview

ScribeSTT 是 ARX 平台上的語音與影像轉錄應用程式，能把影音檔案裡的說話內容轉換成帶有時間軸的逐字稿。

知識庫是由文字構成的。把錄音轉成帶時間軸的逐字稿，正是讓 AI 得以檢索音訊與影片的前提。

本文涵蓋四個情境，彼此獨立，可依需要挑選閱讀：

- **情境 1 · 轉錄上傳的檔案**：把影音檔案送進 ScribeSTT，取回逐字稿
- **情境 2 · 串接 NAS**：接上既有的檔案伺服器，批次轉錄裡面已經存在的檔案
- **情境 3 · MCP 整合**：讓 AI Agent 自行連接 ScribeSTT，並探詢音訊該送往何處
- **情境 4 · CLI 整合**：把轉錄接進腳本、排程或 CI 流程

## 適用產品

- ARX OS 1.0 以上
- ScribeSTT 1.0 以上

## 前置準備

請先確認以下兩項：

- 已從 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
> **單次上傳限制**：20 個檔案；每個檔案 1 GB

### 2. 檢視逐字稿

1. 於 **Transcriptions** 頁面點擊要檢視的檔案那一列
2. 對話框開啟後，提供 srt、txt、json 三種格式

### 3. 下載逐字稿

1. 於 **Transcriptions** 頁面選取要下載的檔案
2. 點擊 **Download** 下拉按鈕，再點選需要的逐字稿格式

---

## 情境 2. 串接 NAS，批次轉錄既有的錄音檔

當公司的錄音檔已經存放在 NAS 上，就不需要一個一個上傳。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 Agent 透過 MCP 連接 ScribeSTT

前兩個情境都是人在網頁介面上操作。若要讓 AI Agent —— Claude Code、Cursor，或你公司自行開發的代理 —— 自行連接 ScribeSTT，可透過 ScribeSTT 的 **HTTP MCP** 介面串接。

先釐清 MCP 目前的涵蓋範圍：它是代理確認連線、並探詢音訊該送往何處的管道。轉錄工作本身仍透過 REST API 或 CLI 執行（情境 4）。

串接完成後，代理可呼叫以下兩個工具：

<table>
<thead>
  <tr>
    <th>
      工具
    </th>
    
    <th>
      用途
    </th>
    
    <th>
      權限層級
    </th>
    
    <th>
      資料來源限制
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        arxstt_get_system_version
      </code>
    </td>
    
    <td>
      回傳伺服器版本、git SHA 與建置時間，可用來確認連線是否正常
    </td>
    
    <td>
      不限層級
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        arxstt_list_capabilities
      </code>
    </td>
    
    <td>
      列出這組憑證可呼叫的工具；若該憑證允許上傳，另外回傳音訊上傳的端點。每次連線都應先呼叫這一個
    </td>
    
    <td>
      不限層級
    </td>
    
    <td>
      —
    </td>
  </tr>
</tbody>
</table>

> ⚠️ **MCP 預設為關閉**
> 這個端點屬於新增的攻擊面，因此每一套部署都必須自行啟用。請透過 `mcp.enabled` 設定或 `ARXSTT_MCP_ENABLED` 環境變數開啟。

> ⚠️ **音訊不會經過 MCP 傳輸**
> MCP 的請求主體上限為 256 KB，而這個額度只涵蓋工具呼叫的參數。音訊改走另一個 REST 端點，因此驅動代理的環境必須能夠發出 HTTP 請求（`curl`、Python `requests`，或工作流引擎的 HTTP 節點都可以）。
> 純聊天介面若無法執行程式碼或發送 HTTP 請求，就完全無法送出音訊。

### 1. 建立存取用的 PAT

MCP 連線以 **PAT（個人存取權杖）** 進行驗證，由超級管理員在網頁介面簽發。

1. 開啟 ScribeSTT 並前往使用者頁面
2. 在要授權的使用者那一列的操作欄，點擊「Manage Personal Access Token」
3. 於「Personal Access Tokens」對話框中點擊「Create」按鈕
4. 於「Create Personal Access Token」對話框設定權杖名稱、操作權限、可存取的資料夾與有效期限
5. 取得產生的權杖

> ⚠️ **請立即保存權杖**
> 權杖一產生就要存放到代理啟動時能讀取的位置。遺失後唯一的辦法是重新建立一組。

建立 PAT 時需要決定兩種範圍：

- **操作範圍**：`read_only` 僅能查詢，`default` 另可建立、更新、取消、重試與觸發，`destructive` 另可刪除。每個工具都會宣告自己接受哪些層級
- **資料存取範圍**：這組 PAT 可觸及哪些資料來源。留空則**一律拒絕**

### 2. 在 AI Agent中設定 MCP 伺服器

將以下連線資訊填入代理的 MCP 設定：

<table>
<thead>
  <tr>
    <th>
      項目
    </th>
    
    <th>
      值
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Endpoint
    </td>
    
    <td>
      <code>
        https://<ScribeSTT-host>/mcp
      </code>
      
       —— 預設路徑，可透過 <code>
        mcp.endpoint
      </code>
      
       設定或 <code>
        ARXSTT_MCP_ENDPOINT
      </code>
      
       環境變數調整
    </td>
  </tr>
  
  <tr>
    <td>
      Transport
    </td>
    
    <td>
      Streamable HTTP
    </td>
  </tr>
  
  <tr>
    <td>
      驗證
    </td>
    
    <td>
      <code>
        Authorization: Bearer <YOUR_PAT>
      </code>
      
      ，PAT 的形式為 <code>
        arxstt_pat_…
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      單次請求上限
    </td>
    
    <td>
      256 KB，由 <code>
        mcp.maxRequestBodyBytes
      </code>
      
       或 <code>
        ARXSTT_MCP_MAXREQUESTBODYBYTES
      </code>
      
       設定。這個額度計算的是工具呼叫的參數，音訊不會經過此端點
    </td>
  </tr>
</tbody>
</table>

> 💡 **如何取得 <ScribeSTT-host>**
> 前往 ARX 桌面，在 ScribeSTT 圖示上按右鍵，選擇於新分頁開啟，再從網址欄複製網域。

以 Claude Code 為例，設定如下：

```json
{
  "mcpServers": {
    "ScribeSTT": {
      "type": "http",
      "url": "https://<ScribeSTT-host>/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_PAT>"
      }
    }
  }
}
```

### 3. 上傳音訊並建立轉錄

請先呼叫 `arxstt_list_capabilities`。當 PAT 的層級為 `default` 或更高時，回應會帶有 `uploadEndpoint` 描述，說明要送往的路徑與可接受的欄位 —— 請由此讀取路徑，而不要寫死。純 `read_only` 的 PAT 完全拿不到上傳端點。

<table>
<thead>
  <tr>
    <th>
      項目
    </th>
    
    <th>
      值
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      上傳端點
    </td>
    
    <td>
      <code>
        POST /api/v1/transcriptions/upload
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      驗證
    </td>
    
    <td>
      與 MCP 連線相同的 Bearer PAT
    </td>
  </tr>
  
  <tr>
    <td>
      Content type
    </td>
    
    <td>
      <code>
        multipart/form-data
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      檔案大小上限
    </td>
    
    <td>
      預設 1 GiB，由 <code>
        upload.maxFileSizeBytes
      </code>
      
       或 <code>
        ARXSTT_UPLOAD_MAXFILESIZEBYTES
      </code>
      
       設定
    </td>
  </tr>
</tbody>
</table>

表單欄位為 `audioFile`（必填），以及選填的 `language`（`zh`、`en`、`ja` 或 `ko`；不填則自動偵測）、`glossaryId` 與 `outputFormats`（`txt`、`srt`、`json`；不填則產出全部三種）。

上傳範例：

```bash
curl -X POST https://<ScribeSTT-host>/api/v1/transcriptions/upload \
  -H "Authorization: Bearer <YOUR_PAT>" \
  -F "audioFile=@meeting.mp3" \
  -F "language=en"
```

回應會帶回該筆轉錄的 `id`。

> ⚠️ **沒有任何 MCP 工具會回傳逐字稿**
> 上述兩個工具只涵蓋連線與探詢。上傳被接受之後，請透過 REST API 或 CLI 追蹤轉錄狀態並取得文字內容 —— 見情境 4。

---

## 情境 4. AI Agent 透過 CLI 以 ScribeSTT 轉錄音訊

CLI 是單一執行檔，適合腳本、排程任務、CI 流程，或讓具備 shell 權限的代理直接下指令。它是為自動化設計的：每個命令都支援 `--json` 輸出，並以結束代碼分類錯誤，讓程式能決定下一步怎麼做。

命令一覽：

<table>
<thead>
  <tr>
    <th>
      分組
    </th>
    
    <th>
      命令
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      驗證
    </td>
    
    <td>
      <code>
        auth login
      </code>
      
      、<code>
        auth status
      </code>
      
      、<code>
        auth logout
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      轉錄
    </td>
    
    <td>
      <code>
        transcription upload
      </code>
      
      、<code>
        transcription get
      </code>
      
      、<code>
        transcription list
      </code>
      
      、<code>
        transcription output
      </code>
      
      、<code>
        transcription cancel
      </code>
      
      、<code>
        transcription retry
      </code>
      
      、<code>
        transcription delete
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      批次任務
    </td>
    
    <td>
      <code>
        task create
      </code>
      
      、<code>
        task get
      </code>
      
      、<code>
        task list
      </code>
      
      、<code>
        task trigger
      </code>
      
      、<code>
        task delete
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      批次執行
    </td>
    
    <td>
      <code>
        run get
      </code>
      
      、<code>
        run list
      </code>
      
      、<code>
        run cancel
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      資料來源
    </td>
    
    <td>
      <code>
        datasource list
      </code>
      
      、<code>
        datasource get
      </code>
      
      、<code>
        datasource entries
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      術語庫
    </td>
    
    <td>
      <code>
        glossary create
      </code>
      
      、<code>
        glossary get
      </code>
      
      、<code>
        glossary list
      </code>
      
      、<code>
        glossary delete
      </code>
    </td>
  </tr>
</tbody>
</table>

所有命令共通的旗標：`--server <url>`、`--token <PAT>`、`--config <path>`、`--json`、`--fields <欄位清單>`

> 💡 **每個命令都會自我描述**`arx-stt --help --json` 會列出整棵命令樹，`arx-stt transcription get --help --json` 則列出單一命令的參數、旗標與輸出欄位。代理可以自行探詢，不必依賴外部說明。

### 1. 安裝 CLI

ScribeSTT 伺服器本身就提供執行檔，不需要外部套件庫。以下指令會安裝到 `~/.local/bin`，不需要 sudo：

```bash
export ARXSTT_SERVER="https://<ScribeSTT-host>"

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-%E5%BB%BA%E7%AB%8B%E5%AD%98%E5%8F%96%E7%94%A8%E7%9A%84-pat)。

```bash
# Store the PAT (this non-interactive form is the one to use for automation)
arx-stt auth login --server https://<ScribeSTT-host> --token <YOUR_PAT>

# Or pipe it in, to keep the token out of your command history
echo <YOUR_PAT> | arx-stt auth login --server https://<ScribeSTT-host>

# Or just set the environment variable, writing nothing to disk
export ARXSTT_TOKEN=<YOUR_PAT>
```

接著驗證：

```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` 預設輸出到 stdout，可用 `--format txt|srt|json` 或 `--out FILE` 調整。

加上 `--wait` 後，結束代碼即代表結果：`0` 為完成或略過，`5` 為失敗或已取消，`4` 為逾時。逾時不會中止伺服器端的處理 —— 再執行一次 `transcription get --wait` 即可繼續觀察。

取消、重試與刪除紀錄分別是 `transcription cancel <id>`、`transcription retry <id>` 與 `transcription delete <id>`。重試適用於失敗與已取消的紀錄，不適用於已略過的紀錄；刪除需要 `destructive` 層級的 PAT。

### 4. 批次轉錄

批次作業由三種物件組成：**資料來源**（檔案放在哪裡）、**任務**（靜態設定），以及**執行**（一次實際的執行紀錄）。

#### 選定資料來源

```bash
arx-stt datasource list --scheme smb --json
arx-stt datasource entries <datasourceId> --path recordings/ --json
```

`datasource entries` 用來瀏覽資料夾，以便挑選來源路徑。本機檔案系統的資料來源由系統管理，不會出現在清單中。

#### 建立任務

```bash
arx-stt task create --name nightly \
  --source-datasource <datasourceId> --source-path recordings/ \
  --target-datasource <datasourceId> --target-path transcripts/ \
  --output-format txt --scan-depth 2 --json
```

- `--scan-depth`：向下掃描幾層資料夾
- `--glossary`：對任務中的每個檔案套用術語庫

#### 執行與監控

```bash
run=$(arx-stt task trigger <taskId> --json | jq -r .runId)
arx-stt run get "$run" --json --wait
arx-stt run list --task <taskId> --status failed --json
```

`task trigger` 會建立一次執行，掃描來源資料夾並印出 `runId`。在 `run get` 加上 `--wait` 後，結束代碼 `0` 代表完成，`5` 代表部分完成、失敗或已取消。`run cancel <id>` 會取消該次執行，並連帶取消其底下仍在進行的轉錄。

刪除任務需要 `destructive` 層級的 PAT，且該任務仍有執行在進行時無法刪除。

#### 術語庫

```bash
arx-stt glossary create --name product-names \
  --term "scribe stt=ScribeSTT" --term "ardge=ARDGE" --json
```

每一個 `--term` 都是把辨識容易產生的錯誤形式，對應到你希望出現在逐字稿裡的正確形式。修改既有術語庫的詞條屬於網頁介面的工作，CLI 負責建立、查詢與刪除。

### 5. 自動化時的注意事項

錯誤以結束代碼分類，因此腳本可以直接依代碼分支，不必去解析錯誤文字：

<table>
<thead>
  <tr>
    <th>
      結束代碼
    </th>
    
    <th>
      代表什麼
    </th>
    
    <th>
      該怎麼做
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        0
      </code>
    </td>
    
    <td>
      成功
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        1
      </code>
    </td>
    
    <td>
      用戶端錯誤 —— 輸入有誤或找不到目標
    </td>
    
    <td>
      修正輸入，不要重試
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        2
      </code>
    </td>
    
    <td>
      驗證或授權失敗
    </td>
    
    <td>
      <strong>
        不要自動重試。
      </strong>
      
       PAT 無效或層級不足 —— 請更換 PAT
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        3
      </code>
    </td>
    
    <td>
      伺服器錯誤（5xx）
    </td>
    
    <td>
      稍後重試
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        4
      </code>
    </td>
    
    <td>
      網路或暫時性錯誤，包含輪詢逾時
    </td>
    
    <td>
      以退避策略重試
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        5
      </code>
    </td>
    
    <td>
      作業已進入失敗、已取消或部分完成的終態
    </td>
    
    <td>
      檢視 JSON 輸出中的 <code>
        errorCode
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        130
      </code>
    </td>
    
    <td>
      以 Ctrl-C 中斷
    </td>
    
    <td>
      使用者主動中止
    </td>
  </tr>
</tbody>
</table>

JSON 格式的錯誤會輸出到 stdout，形式為 `{"errors":{"code":…,"message":…,"hint":…}}`。

代理在使用 CLI 時，請遵守以下幾點：

- **一律加上 --json**：表格輸出是給人看的，程式無法可靠地解析
- **用 --fields 縮小輸出**：例如 `--fields id,status` —— 只取需要的欄位可以節省 context
- **沒有 --dry-run**：`create`、`trigger` 與 `delete` 都會立即生效。變更或刪除之前，請先用 `get <id>` 確認目標
- **依結束代碼分支，不要依訊息文字**：代碼是穩定的契約，文字不是


## Sitemap

See the full [sitemap](https://docs.ardge.com/sitemap.md) for all pages.