金大哥 - thoth-mcp MCP 详情

article

README

🚀 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 安装的步骤如下：

访问 Smithery 上的 Thoth MCP 服务器。
点击“安装”。
提示时输入你的 Thoth API 密钥。
立即在 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 .

贡献

欢迎贡献代码！请遵循以下步骤：

分叉仓库。
创建一个功能分支 (git checkout -b feature/amazing-feature)。
提交你的更改 (git commit -m 'Add amazing feature')。
将更改推送到分支 (git push origin feature/amazing-feature)。
打开一个拉取请求。

请确保你的代码：

遵循现有的 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

thoth-mcp

README

🚀 Thoth MCP 服务器

🚀 快速开始

✨ 主要特性

📦 安装指南

通过 MCP 注册表（推荐）

通过 Smithery（零配置部署）

全局安装（通过 npx）

本地开发

💻 使用示例

基础用法

运行服务器

Stdio 模式（本地）

远程 HTTP 服务器模式

环境变量

高级用法

创建多平台帖子

安排帖子发布

检索帖子数据

访问资源

本地测试 HTTP 模式

📚 详细文档

Claude 代码插件

它是什么？

插件快速开始

文档

MCP 客户端配置

Claude Desktop

其他 MCP 客户端

可用工具

create-post

get-post

get-all-posts

update-post

get-brand-styles

get-brand-style

可用资源

post://{postId}

preview://{postId}/{platform}

API 集成

错误处理

🔧 技术细节

开发

构建

本地运行

类型检查

开发模式（监听）

变更日志

v1.3.0 (2025-10-10)

v1.2.0 (2025-10-08)

v1.0.3 (2025-10-08)

v1.0.2 (2025-10-08)

v1.0.1 (2025-10-08)

v1.0.0 (2025-10-08)

📄 许可证

故障排除

服务器无法启动

工具调用失败

HTTP 模式无法访问

Smithery 部署失败

贡献

维护者指南

支持

运行方式说明

托管运行

本地运行 / 其它方式