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