> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# TokenLab MCP Server

> 將 MCP 客戶端連接至 TokenLab 模型探索、定價、OpenAI 相容聊天與原生推論端點。

[TokenLab MCP server](https://github.com/hedging8563/tokenlab-mcp-server) 為支援 MCP 的代理程式提供即時模型探索、定價、OpenAI 相容 Chat Completions 與原生推論工具。

當代理程式需要比較模型、檢查支援的請求格式、查詢定價，或透過 OpenAI Chat Completions、Responses、Anthropic Messages、Gemini generateContent 呼叫 TokenLab 時，請使用此伺服器。

<Note>
  公開目錄工具不需要 TokenLab API 金鑰。設定 `TOKENLAB_API_KEY` 後可使用四個付費推論工具。
</Note>

## 它提供了什麼

* 來自 `https://api.tokenlab.sh/v1/models` 的即時模型探索。
* 來自 `/v1/models/{model}` 的模型詳細資訊查詢。
* 來自 `/v1/models/{model}/pricing` 的定價查詢。
* 來自 `https://api.tokenlab.sh/llms.txt` 的代理程式可讀 API 概覽。
* 針對 OpenAI 相容聊天、Responses、Anthropic Messages、Gemini、媒體、音訊、嵌入（embeddings）、重排序（rerank）及翻譯的端點系列指南。
* 透過 OpenAI 相容 Chat Completions、Responses、Anthropic Messages 與 Gemini generateContent 進行選用推論。

## 從 GitHub 安裝

複製公開儲存庫並安裝依賴項：

```bash theme={null}
git clone https://github.com/hedging8563/tokenlab-mcp-server.git
cd tokenlab-mcp-server
npm install
npm test
```

透過 stdio 啟動伺服器：

```bash theme={null}
npm start
```

選用的 `TOKENLAB_API_BASE` 環境變數預設為 `https://api.tokenlab.sh`。

## 在 Codex 中安裝

將公開目錄伺服器新增至 Codex 設定：

```bash theme={null}
codex mcp add tokenlab-model-catalog -- npx -y @tokenlabai/mcp-server
```

新增後請開啟新的 Codex 工作階段。公開目錄工具不需要 `TOKENLAB_API_KEY`。

如需啟用推論工具，請在新增伺服器時傳入 TokenLab API 金鑰：

```bash theme={null}
codex mcp add --env TOKENLAB_API_KEY=your-tokenlab-api-key tokenlab-model-catalog -- npx -y @tokenlabai/mcp-server
```

## 在 Cline 中安裝

使用 Cline CLI 安裝已發佈的 stdio 伺服器：

```bash theme={null}
cline mcp add tokenlab --yes -- npx -y @tokenlabai/mcp-server
```

此命令已透過 Cline CLI 驗證，可在沒有安裝警告的情況下完成。公共目錄工具可立即使用；需要推論工具時，請在 Cline 環境中設定 `TOKENLAB_API_KEY`。

## Claude Desktop 設定

將已發佈的 npm 套件新增至 MCP 客戶端設定：

```json theme={null}
{
  "mcpServers": {
    "tokenlab-model-catalog": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server"]
    }
  }
}
```

儲存設定後，請重新啟動 MCP 客戶端。

## Cursor、Windsurf 及其他 MCP 客戶端

在任何支援 stdio MCP 伺服器的客戶端中使用相同的指令與參數：

```json theme={null}
{
  "command": "npx",
  "args": ["-y", "@tokenlabai/mcp-server"],
  "env": {
    "TOKENLAB_API_BASE": "https://api.tokenlab.sh"
  }
}
```

如果您的客戶端儲存了已命名的伺服器，請使用 `tokenlab-model-catalog` 作為伺服器名稱。

## 工具

| 工具                         | 用途                                                                                                      |
| -------------------------- | ------------------------------------------------------------------------------------------------------- |
| `list_models`              | 列出公開的 TokenLab 模型。可選擇使用 `recommended_for` 進行篩選，例如 `image`、`video`、`embedding`、`rerank` 或 `translation`。 |
| `get_model`                | 獲取單一模型的公開詳細資訊與支援的請求格式。                                                                                  |
| `get_model_pricing`        | 獲取單一模型的公開定價詳細資訊。                                                                                        |
| `compare_models`           | 比較多個模型 ID 的詳細資訊與定價。                                                                                     |
| `create_chat_completion`   | 呼叫 OpenAI 相容的 `/v1/chat/completions` 端點，支援多模態訊息與工具呼叫。需要 `TOKENLAB_API_KEY`。                             |
| `create_response`          | 使用字串或結構化 input、tools、tool choice、metadata 與 text 設定呼叫 `/v1/responses`。需要 `TOKENLAB_API_KEY`。            |
| `create_anthropic_message` | 使用原生多訊息 content blocks 與 tools 呼叫 `/v1/messages`。需要 `TOKENLAB_API_KEY`。                                 |
| `create_gemini_content`    | 使用 contents、多模態 parts、tools 與 generation config 呼叫原生 `generateContent`。需要 `TOKENLAB_API_KEY`。           |
| `get_api_overview`         | 獲取 TokenLab 的 `llms.txt` 概覽，以供代理程式讀取端點指南。                                                               |

推論工具會回傳一般 JSON 結果。MCP 工具呼叫會刻意停用串流輸出。

## 建議的代理程式工作流程

1. 當使用者未指定模型時，呼叫 `list_models`。
2. 針對非聊天任務（如圖像、影片、音樂、3D、TTS、STT、嵌入、重排序或翻譯）使用 `recommended_for`。
3. 在建立非聊天請求、重試失敗請求或切換端點系列之前，呼叫 `get_model`。
4. 當模型成本影響使用者選擇時，呼叫 `get_model_pricing`。
5. 當選擇取決於多個候選模型時，使用 `compare_models`。
6. 呼叫符合所需 API 契約的推論工具，或使用 `get_api_overview` 取得 TokenLab API 系列的精簡對照表。

## 原生端點指南

TokenLab 支援 OpenAI 相容路由與原生端點系列。MCP 伺服器可協助代理程式在編寫程式碼前選擇正確的路由：

| 系列                     | 常見路由                                                                     |
| ---------------------- | ------------------------------------------------------------------------ |
| OpenAI-compatible chat | `/v1/chat/completions`                                                   |
| Responses              | `/v1/responses`                                                          |
| Anthropic Messages     | `/v1/messages`                                                           |
| Gemini native          | `/v1beta/models/{model}:generateContent`                                 |
| Images                 | `/v1/images/generations`, `/v1/images/edits`                             |
| Video                  | `/v1/videos/generations`                                                 |
| Music                  | `/v1/music/generations`                                                  |
| 3D                     | `/v1/3d/generations`                                                     |
| Audio                  | `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/audio/translations` |
| Embeddings and rerank  | `/v1/embeddings`, `/v1/rerank`                                           |
| Text translation       | `/v1/translations`                                                       |

## 託管模型瀏覽器

支援 Streamable HTTP 的客戶端可以連線至：

```text theme={null}
https://tokenlab-model-explorer.vercel.app/mcp
```

此託管瀏覽器公開提供 `open_tokenlab_model_explorer`、`compare_tokenlab_models` 與 `generate_tokenlab_endpoint_example`。需要完整九個工具或帶憑證的推論時，請使用上方的本機 npm 伺服器。

## 與 TokenLab Skills 搭配使用

MCP 伺服器在執行階段非常有用，而 [TokenLab skills repository](https://github.com/hedging8563/tokenlab-skills) 則教導編碼代理程式如何產生與修復整合程式碼。

在可用時同時使用兩者：

* MCP server：探索當前模型、定價與端點詳細資訊。
* `tokenlab-api-integration` skill：產生可執行的 API 範例並處理結構化的 TokenLab 錯誤。
* `tokenlab-model-picker` skill：為使用者的任務選擇合適的模型。
* `tokenlab-native-endpoints` skill：決定何時使用 Responses、Anthropic Messages、Gemini、媒體、音訊、嵌入、重排序或翻譯路由。

## 疑難排解

<AccordionGroup>
  <Accordion title="客戶端無法啟動伺服器">
    確認 Node.js 至少為 18.17，然後在終端機執行一次 `npx -y @tokenlabai/mcp-server`，以查看 npm 或網路錯誤。
  </Accordion>

  <Accordion title="模型列表為空">
    請驗證機器是否能連線至 `https://api.tokenlab.sh/v1/models`。如果您覆寫了 `TOKENLAB_API_BASE`，請確保結尾不包含斜線。
  </Accordion>

  <Accordion title="代理程式仍選擇過時的模型 ID">
    請要求代理程式在硬編碼模型名稱之前呼叫 `list_models` 或 `get_model`。將 MCP 伺服器與 `tokenlab-model-picker` 搭配使用可獲得更好的結果。
  </Accordion>

  <Accordion title="此伺服器可以呼叫付費的 TokenLab 推論 API 嗎？">
    可以。設定 `TOKENLAB_API_KEY` 後，可使用 `create_chat_completion`、`create_response`、`create_anthropic_message` 或 `create_gemini_content`。目錄與定價工具無需金鑰仍可使用。
  </Accordion>
</AccordionGroup>

## 資源

<CardGroup cols={2}>
  <Card title="GitHub 儲存庫" icon="github" href="https://github.com/hedging8563/tokenlab-mcp-server">
    原始碼與本地設定說明
  </Card>

  <Card title="TokenLab Skills" icon="sparkles" href="https://github.com/hedging8563/tokenlab-skills">
    維護中的 TokenLab 整合代理程式技能
  </Card>

  <Card title="模型目錄 API" icon="list" href="https://api.tokenlab.sh/v1/models">
    公開模型探索端點
  </Card>

  <Card title="llms.txt" icon="file-lines" href="https://api.tokenlab.sh/llms.txt">
    代理程式可讀的 TokenLab API 概覽
  </Card>

  <Card title="Glama MCP Server" icon="globe" href="https://glama.ai/mcp/servers/hedging8563/tokenlab-mcp-server">
    查看已驗證的 TokenLab MCP Server 項目
  </Card>

  <Card title="Glama 模型瀏覽器" icon="search" href="https://glama.ai/mcp/servers/hedging8563/tokenlab-openai-apps-model-explorer">
    瀏覽模型、定價與原生端點範例
  </Card>

  <Card title="MCP.so 項目" icon="compass" href="https://mcp.so/servers/tokenlab-mcp-server">
    在 AI & Agents 目錄中探索 TokenLab
  </Card>

  <Card title="託管模型瀏覽器" icon="rocket" href="https://tokenlab-model-explorer.vercel.app">
    開啟公共模型瀏覽器與遠端 MCP 端點
  </Card>
</CardGroup>