Thoth MCP

🚀 Thoth MCP 服務器

Thoth MCP 服務器是為 Thoth 內容創作平臺打造的 Model Context Protocol (MCP) 服務器。藉助該服務器，AI 助手和工具能夠通過 Thoth 的 API 來創建和獲取內容。

✨ 新特性： Claude 代碼插件現已推出，支持斜槓命令和專業 AI 代理，可簡化內容創作工作流程！

🚀 快速開始

# 通過 npx 安裝
npx @usethoth/mcp-server --api-key YOUR_API_KEY

# 或者在 Claude Desktop 中進行配置（詳見下方配置說明）

你可以在 app.usethoth.com/settings/api-keys 獲取 API 密鑰。

✨ 主要特性

• 內容創作：藉助 AI 增強功能，生成針對平臺優化的內容。
• 帖子檢索與管理：通過分頁功能獲取、列出和更新帖子數據。
• 多平臺支持：支持 Twitter、Instagram、LinkedIn、Facebook、Threads、博客、Reddit 等平臺。
• 品牌風格：使用品牌預設，應用一致的語氣、語調及視覺風格。
• 圖像生成：可選擇為內容生成圖像。
• 日程安排：安排帖子在未來發布。
• 雙傳輸模式：支持 stdio（本地）和 HTTP 傳輸（Smithery/雲部署）。
• 類型安全：採用 TypeScript 和 Zod 驗證構建。

📦 安裝指南

通過 MCP 註冊表（推薦）

該服務器已在 官方 MCP 註冊表 中發佈，名稱為 io.github.zeiq-co/thoth-mcp。

你可以通過註冊表的網頁界面瀏覽並安裝，也可以直接在 MCP 客戶端中進行配置（詳見 MCP 客戶端配置）。

通過 Smithery（零配置部署）

通過 Smithery 開始使用是最簡單的方式，它提供以下功能：

• 一鍵安裝：無需本地依賴或配置。
• 自動更新：始終使用最新版本。
• 安全託管：安全管理你的 API 密鑰。
• 交互式遊樂場：在使用工具前進行測試。

從 Smithery 安裝的步驟如下：

1. 訪問 Smithery 上的 Thoth MCP 服務器。
2. 點擊“安裝”。
3. 提示時輸入你的 Thoth API 密鑰。
4. 立即在 Claude Desktop 或其他 MCP 客戶端中開始使用。

全局安裝（通過 npx）

npx @usethoth/mcp-server --api-key YOUR_API_KEY

本地開發

git clone https://github.com/perminder-klair/thoth-mcp.git
cd thoth-mcp
pnpm install
pnpm build

💻 使用示例

基礎用法

運行服務器

Stdio 模式（本地）

這是與 Claude Desktop 等 MCP 客戶端配合使用的默認模式：

npx @usethoth/mcp-server --api-key YOUR_API_KEY

或者使用 MCP 檢查器進行調試：

npx @modelcontextprotocol/inspector npx @usethoth/mcp-server --api-key YOUR_API_KEY

使用自定義基礎 URL：

npx @usethoth/mcp-server \
  --api-key YOUR_API_KEY \
  --base-url https://app.usethoth.com

遠程 HTTP 服務器模式

在 HTTP 模式下運行服務器，用於雲部署（如 Smithery）或通過 HTTP 公開服務器：

npx @usethoth/mcp-server --remote --api-key YOUR_API_KEY

服務器將在端口 8081（可通過 PORT 環境變量配置）上啟動一個 HTTP 服務器，包含以下端點：

• /mcp - 主要 MCP 端點（POST）
• /health - 健康檢查端點（GET）

使用自定義配置：

PORT=3000 npx @usethoth/mcp-server \
  --remote \
  --api-key YOUR_API_KEY \
  --base-url https://app.usethoth.com

注意：在 HTTP 模式下，服務器實現了 MCP 可流式 HTTP 傳輸，併為基於瀏覽器的客戶端進行了適當的 CORS 配置。

環境變量

你可以使用環境變量代替命令行標誌： 對於 stdio 模式：

export THOTH_API_KEY=your_api_key
export THOTH_BASE_URL=http://localhost:3000
npx @usethoth/mcp-server

對於 HTTP 模式：

export THOTH_API_KEY=your_api_key
export THOTH_BASE_URL=https://www.usethoth.com
export PORT=8081
npx @usethoth/mcp-server --remote

可用的環境變量：

• THOTH_API_KEY - 你的 Thoth API 密鑰（僅 stdio 模式；HTTP 模式使用查詢參數）
• THOTH_BASE_URL - Thoth API 的基礎 URL（默認：https://www.usethoth.com）
• PORT - HTTP 服務器端口（僅 HTTP 模式，默認：8081）

高級用法

創建多平臺帖子

// 使用 create-post 工具
{
  "content": "Excited to share our latest feature! \ud83d\ude80 AI-powered content optimization for all your social platforms.",
  "platforms": ["twitter", "linkedin", "instagram"],
  "length": "medium",
  "createImage": true,
  "createHashtags": true
}

安排帖子發佈

{
  "content": "Join us for our product launch next week!",
  "platforms": ["twitter", "linkedin"],
  "scheduleTime": "2025-10-20T14:00:00Z",
  "createImage": true
}

檢索帖子數據

// 使用 get-post 工具
{
  "postId": "123e4567-e89b-12d3-a456-426614174000"
}

訪問資源

// 讀取帖子資源
{
  "uri": "post://123e4567-e89b-12d3-a456-426614174000"
}

// 讀取特定平臺的預覽
{
  "uri": "preview://123e4567-e89b-12d3-a456-426614174000/twitter"
}

本地測試 HTTP 模式

啟動 HTTP 模式的服務器：

npx @usethoth/mcp-server --remote --api-key YOUR_API_KEY

測試健康檢查端點：

curl http://localhost:8081/health

使用 MCP 檢查器測試 MCP 端點：

npx @modelcontextprotocol/inspector http://localhost:8081/mcp?apiKey=YOUR_API_KEY

或者與支持基於查詢配置的可流式 HTTP MCP 客戶端一起使用。

📚 詳細文檔

Claude 代碼插件

新特性！ 我們創建了一個官方的 Claude 代碼插件，通過用戶友好的命令和專業的 AI 代理，讓社交媒體內容創作變得更加輕鬆。

它是什麼？

Thoth 為 Claude 代碼提供的插件具備以下功能：

• 5 個斜槓命令：快速訪問常見工作流程

  • /create-content - 在 AI 指導下創建多平臺帖子
  • /schedule-post - 安排帖子在最佳互動時間發佈
  • /view-brands - 瀏覽和管理你的品牌風格
  • /manage-posts - 列出、過濾和管理所有帖子
  • /preview-post - 預覽特定平臺的內容格式

• 3 個專業代理：針對特定任務的專業 AI 助手

  • 內容創作者 - 擅長創作引人入勝、針對平臺優化的內容
  • 品牌經理 - 確保所有平臺上的品牌一致性
  • 社交媒體優化器 - 通過數據驅動的策略最大化覆蓋範圍和互動率

插件快速開始

# 安裝插件
claude plugin install thoth

# 設置你的 API 密鑰
export THOTH_API_KEY="your-api-key-here"

# 開始創作內容
claude /create-content "Announcing our new feature"

# 或者使用代理
claude "Content Creator, help me announce our product launch"

文檔

完整的插件文檔、安裝說明和使用示例可在 claude-code-plugin 目錄中找到。

請參閱 claude-code-plugin/README.md 瞭解以下內容：

• 詳細的安裝說明
• 完整的命令參考
• 代理使用指南
• 高級工作流程和示例
• 故障排除提示

MCP 客戶端配置

Claude Desktop

將以下內容添加到你的 Claude Desktop 配置文件中： macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "thoth": {
      "command": "npx",
      "args": [
        "@usethoth/mcp-server",
        "--api-key",
        "YOUR_API_KEY",
        "--base-url",
        "http://localhost:3000"
      ]
    }
  }
}

其他 MCP 客戶端

對於支持 stdio 傳輸的其他 MCP 客戶端，使用類似的配置，並使用適當的命令和參數。

可用工具

服務器提供了 6 個用於管理 Thoth 內容的工具：

工具	描述
create-post	使用 AI 增強功能創建多平臺內容
get-post	通過 ID 檢索特定帖子
get-all-posts	分頁並過濾列出帖子
update-post	更新現有帖子的標題、內容或狀態
get-brand-styles	列出所有可用的品牌風格
get-brand-style	獲取詳細的品牌風格配置

create-post

創建具有特定平臺變體的新內容帖子。 參數：

• content（必需）：要增強的原始內容
• platforms（必需）：目標平臺數組
  • 選項：twitter、instagram、linkedin、facebook、threads、blog、reddit
• length（可選）：內容長度 - very-short、short、medium、long（默認：medium）
• createImage（可選）：生成圖像（默認：false）
• createHashtags（可選）：生成主題標籤（默認：true）
• scheduleTime（可選）：ISO 8601 日期時間，用於安排帖子發佈
• postToSocialNetworks（可選）：立即發佈到已連接的網絡（默認：false）
• brandStyleId（可選）：要應用的品牌風格 UUID

示例：

{
  "content": "Just launched our new AI-powered content creation tool!",
  "platforms": ["twitter", "linkedin"],
  "length": "medium",
  "createImage": true,
  "createHashtags": true
}

返回值：

• 帖子 ID
• 原始內容
• 特定平臺的增強內容
• 生成的圖像（如果請求）
• 每個平臺的主題標籤
• 狀態和時間戳

get-post

通過帖子 ID 檢索帖子。 參數：

• postId（必需）：帖子的 UUID

示例：

{
  "postId": "123e4567-e89b-12d3-a456-426614174000"
}

返回值：

• 完整的帖子數據
• 特定平臺的內容
• 生成的圖像
• 狀態和元數據

get-all-posts

分頁並過濾列出所有帖子。 參數：

• page（可選）：頁碼（默認：1）
• limit（可選）：每頁的帖子數（默認：10）
• status（可選）：按狀態過濾 - draft、scheduled、published

示例：

{
  "page": 1,
  "limit": 20,
  "status": "published"
}

返回值：

• 帶有元數據的帖子數組
• 分頁信息
• 總數

update-post

更新現有帖子。 參數：

• postId（必需）：要更新的帖子的 UUID
• title（可選）：帖子的新標題
• content（可選）：新內容
• status（可選）：新狀態 - draft、scheduled、published

示例：

{
  "postId": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Updated Title",
  "status": "published"
}

返回值：

• 更新後的帖子數據
• 確認消息

get-brand-styles

列出你的賬戶所有可用的品牌風格。 參數：無

返回值：

• 帶有 ID 和名稱的品牌風格數組
• 風格元數據

get-brand-style

獲取特定品牌風格的詳細信息。 參數：

• brandStyleId（必需）：品牌風格的 UUID

示例：

{
  "brandStyleId": "123e4567-e89b-12d3-a456-426614174000"
}

返回值：

• 品牌風格名稱和描述
• 調色板
• 排版設置
• 語氣和語調指南
• 圖像偏好

可用資源

post://{postId}

將帖子數據作為 MCP 資源訪問。 示例 URI：

post://123e4567-e89b-12d3-a456-426614174000

preview://{postId}/{platform}

獲取特定平臺的預覽內容。 示例 URI：

preview://123e4567-e89b-12d3-a456-426614174000/twitter

API 集成

MCP 服務器連接到 Thoth 的 REST API 端點：

• POST /api/v1/posts - 創建新帖子
• GET /api/v1/posts/{postId} - 檢索單個帖子
• GET /api/v1/posts - 分頁列出帖子
• PUT /api/v1/posts/{postId} - 更新現有帖子
• GET /api/v1/brand-styles - 列出品牌風格
• GET /api/v1/brand-styles/{brandStyleId} - 獲取品牌風格詳細信息

所有請求都需要 X-API-Key 頭進行身份驗證。

錯誤處理

服務器為常見問題提供詳細的錯誤消息：

• 無效的 API 密鑰：檢查你的 API 密鑰是否正確且有效。
• 超出速率限制：在進行額外請求之前等待。
• 帖子未找到：驗證帖子 ID 是否正確。
• 無效參數：檢查參數類型和格式。
• 網絡錯誤：驗證基礎 URL 和網絡連接。

🔧 技術細節

開發

構建

pnpm build

本地運行

pnpm start -- --api-key YOUR_API_KEY

類型檢查

pnpm typecheck

開發模式（監聽）

pnpm dev

變更日誌

v1.3.0 (2025-10-10)

• 新增：添加了官方 Claude 代碼插件。
• 新增：5 個斜槓命令，用於簡化內容工作流程。
• 新增：3 個專業 AI 代理（內容創作者、品牌經理、社交媒體優化器）。
• 插件為所有 MCP 服務器功能提供了用戶友好的界面。
• 提供全面的插件文檔和使用示例。
• 為 Claude 代碼用戶增強了開發體驗。

v1.2.0 (2025-10-08)

• 新增：為 Smithery 和雲部署添加了 HTTP 傳輸支持。
• 新增：實現了帶有 /mcp 和 /health 端點的 MCP 可流式 HTTP。
• 服務器現在支持雙傳輸模式：stdio（本地）和 HTTP（遠程）。
• 為 HTTP 服務器添加了 Express 和 CORS 依賴項。
• 添加了用於容器化部署的 Dockerfile。
• 配置為使用適當的 HTTP 運行時進行 Smithery 部署。
• HTTP 模式支持通過查詢參數進行配置。
• 與 Claude Desktop 的 stdio 模式保持向後兼容性。

v1.0.3 (2025-10-08)

• 添加了全面的發佈文檔（PUBLISHING.md）。
• 從配置中移除了所有調試控制檯日誌。
• 改進了貢獻者指南。

v1.0.2 (2025-10-08)

• 關鍵修復：移除了破壞 stdio JSON-RPC 協議的 console.log 語句。
• 將調試輸出更改為 stderr，以防止 JSON 解析錯誤。
• 服務器現在可以與 Claude Desktop 和其他 MCP 客戶端正常工作。

v1.0.1 (2025-10-08)

• 發佈到官方 MCP 註冊表。
• 更新了包元數據。
• 提供完整的工具文檔。

v1.0.0 (2025-10-08)

• 初始版本發佈。
• 支持 6 個 Thoth API 工具。
• 支持多平臺內容創作。
• 集成了品牌風格。

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

故障排除

服務器無法啟動

• 檢查你是否安裝了 Node.js 18+。
• 驗證你的 API 密鑰是否有效。
• 確保基礎 URL 正確且可訪問。

工具調用失敗

• 驗證你的 API 密鑰是否具有所需的權限。
• 檢查是否超出了速率限制。
• 確保帖子 ID 是有效的 UUID。
• 驗證平臺名稱的拼寫是否正確。

HTTP 模式無法訪問

• 檢查端口是否已被使用：lsof -i :8081（或你配置的端口）。
• 驗證防火牆設置是否允許連接。
• 確保服務器進程使用 --remote 標誌運行。
• 檢查服務器日誌中是否有啟動錯誤。
• 驗證 /health 端點是否響應：curl http://localhost:8081/health。
• 對於 Smithery 部署，檢查 Smithery 儀表板中的部署日誌。

Smithery 部署失敗

• 確保你的 GitHub 倉庫是公開的或已連接到 Smithery。
• 驗證 smithery.yaml 和 Dockerfile 是否在倉庫根目錄中。
• 檢查 Smithery 儀表板中的構建日誌，查看具體錯誤。
• 確保所有依賴項都在 package.json 中聲明。
• 嘗試在本地構建 Docker 鏡像：docker build -t thoth-mcp .

貢獻

歡迎貢獻代碼！請遵循以下步驟：

1. 分叉倉庫。
2. 創建一個功能分支 (git checkout -b feature/amazing-feature)。
3. 提交你的更改 (git commit -m 'Add amazing feature')。
4. 將更改推送到分支 (git push origin feature/amazing-feature)。
5. 打開一個拉取請求。

請確保你的代碼：

• 遵循現有的 TypeScript 風格。
• 包含適當的 Zod 模式進行驗證。
• 根據需要更新文檔。
• 通過類型檢查 (pnpm typecheck)。
• 使用 console.error() 進行日誌記錄（不要使用 console.log() - 它會破壞 stdio 模式）。

維護者指南

有關構建和發佈更新的詳細說明，請參閱 PUBLISHING.md。

支持

• Smithery：https://smithery.ai/（一鍵部署）
• MCP 註冊表：https://registry.modelcontextprotocol.io/servers/io.github.zeiq-co/thoth-mcp
• npm 包：https://www.npmjs.com/package/@usethoth/mcp-server
• 文檔：https://docs.usethoth.com
• 問題反饋：https://github.com/perminder-klair/thoth-mcp/issues
• API 參考：https://docs.usethoth.com/api