Thoth MCP Server

Model Context Protocol (MCP) server for Thoth content creation platform. This server enables AI assistants and tools to create and retrieve content through Thoth's API.

✨ NEW: Claude Code Plugin now available with slash commands and specialized AI agents for streamlined content creation workflows!

Quick Start

# Install via npx
npx @usethoth/mcp-server --api-key YOUR_API_KEY

# Or configure in Claude Desktop (see Configuration below)

Get your API key at app.usethoth.com/settings/api-keys

Quick Start
Features
Claude Code Plugin
Installation
Usage
MCP Client Configuration
Available Tools
Available Resources
Development
API Integration
Examples
Troubleshooting
Contributing
Support
Changelog

Features

Create Content: Generate platform-optimized content with AI enhancement
Retrieve & Manage Posts: Fetch, list, and update post data with pagination
Multi-Platform Support: Twitter, Instagram, LinkedIn, Facebook, Threads, Blog, Reddit
Brand Styles: Apply consistent voice, tone, and visual styling with brand presets
Image Generation: Optionally generate images for your content
Scheduling: Schedule posts for future publication
Dual Transport: Supports both stdio (local) and HTTP transports (Smithery/cloud deployment)
Type-Safe: Built with TypeScript and Zod validation

Claude Code Plugin

NEW! We've created an official Claude Code plugin that makes social media content creation even easier with user-friendly commands and specialized AI agents.

What is it?

The Thoth plugin for Claude Code provides:

5 Slash Commands: Quick access to common workflows
- /create-content - Create multi-platform posts with AI guidance
- /schedule-post - Schedule posts for optimal engagement times
- /view-brands - Browse and manage your brand styles
- /manage-posts - List, filter, and manage all your posts
- /preview-post - Preview platform-specific content formatting
3 Specialized Agents: Expert AI assistants for specific tasks
- Content Creator - Expert at crafting engaging, platform-optimized content
- Brand Manager - Ensures brand consistency across all platforms
- Social Media Optimizer - Maximizes reach and engagement through data-driven strategies

Quick Start with Plugin

# Install the plugin
claude plugin install thoth

# Set your API key
export THOTH_API_KEY="your-api-key-here"

# Start creating content
claude /create-content "Announcing our new feature"

# Or use an agent
claude "Content Creator, help me announce our product launch"

Documentation

Full plugin documentation, installation instructions, and usage examples are available in the claude-code-plugin directory.

See claude-code-plugin/README.md for:

Detailed installation instructions
Complete command reference
Agent usage guides
Advanced workflows and examples
Troubleshooting tips

Installation

Via MCP Registry (Recommended)

The server is published in the official MCP Registry as io.github.zeiq-co/thoth-mcp.

Browse and install via the registry web interface, or configure directly in your MCP client (see MCP Client Configuration below).

Via Smithery (Zero-Setup Deployment)

The easiest way to get started is through Smithery, which provides:

One-click installation - No local dependencies or configuration needed
Automatic updates - Always get the latest version
Secure hosting - Your API keys are safely managed
Interactive playground - Test tools before using them

Install from Smithery:

Visit the Thoth MCP Server on Smithery
Click "Install"
Enter your Thoth API key when prompted
Start using immediately in Claude Desktop or other MCP clients

Global Installation (via npx)

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

Local Development

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

Usage

Prerequisites

You'll need a Thoth API key. Generate one at:

Production: https://app.usethoth.com/settings/api-keys
Development: http://localhost:3000/settings/api-keys

Running the Server

Stdio Mode (Local)

This is the default mode for use with MCP clients like Claude Desktop:

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

Or debug with MCP Inspector:

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

With custom base URL:

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

Remote HTTP Server Mode

Run the server in HTTP mode for cloud deployments (like Smithery) or to expose the server over HTTP:

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

The server will start an HTTP server on port 8081 (configurable via PORT environment variable) with:

/mcp - Main MCP endpoint (POST)
/health - Health check endpoint (GET)

With custom configuration:

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

Note: In HTTP mode, the server implements MCP Streamable HTTP transport with proper CORS configuration for browser-based clients.

Environment Variables

Instead of command-line flags, you can use environment variables:

For stdio mode:

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

For HTTP mode:

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

Available environment variables:

THOTH_API_KEY - Your Thoth API key (stdio mode only; HTTP mode uses query params)
THOTH_BASE_URL - Base URL for Thoth API (default: https://www.usethoth.com)
PORT - HTTP server port (HTTP mode only, default: 8081)

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop config file:

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"
      ]
    }
  }
}

Other MCP Clients

For other MCP clients that support stdio transport, use a similar configuration with appropriate command and args.

Available Tools

The server provides 6 tools for managing Thoth content:

Tool	Description
`create-post`	Create multi-platform content with AI enhancement
`get-post`	Retrieve a specific post by ID
`get-all-posts`	List posts with pagination and filtering
`update-post`	Update existing post title, content, or status
`get-brand-styles`	List all available brand styles
`get-brand-style`	Get detailed brand style configuration

create-post

Create a new content post with platform-specific variations.

Parameters:

content (required): The original content to be enhanced
platforms (required): Array of target platforms
- Options: twitter, instagram, linkedin, facebook, threads, blog, reddit
length (optional): Content length - very-short, short, medium, long (default: medium)
createImage (optional): Generate an image (default: false)
createHashtags (optional): Generate hashtags (default: true)
scheduleTime (optional): ISO 8601 datetime to schedule the post
postToSocialNetworks (optional): Immediately post to connected networks (default: false)
brandStyleId (optional): Brand style UUID to apply

Example:

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

Returns:

Post ID
Original content
Platform-specific enhanced content
Generated images (if requested)
Hashtags for each platform
Status and timestamps

get-post

Retrieve a post by its ID.

Parameters:

postId (required): UUID of the post

Example:

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

Returns:

Complete post data
Platform-specific content
Generated images
Status and metadata

get-all-posts

List all posts with pagination and filtering.

Parameters:

page (optional): Page number (default: 1)
limit (optional): Posts per page (default: 10)
status (optional): Filter by status - draft, scheduled, published

Example:

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

Returns:

Array of posts with metadata
Pagination information
Total count

update-post

Update an existing post.

Parameters:

postId (required): UUID of the post to update
title (optional): New title for the post
content (optional): New content
status (optional): New status - draft, scheduled, published

Example:

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

Returns:

Updated post data
Confirmation message

get-brand-styles

List all available brand styles for your account.

Parameters: None

Returns:

Array of brand styles with IDs and names
Style metadata

get-brand-style

Get details for a specific brand style.

Parameters:

brandStyleId (required): UUID of the brand style

Example:

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

Returns:

Brand style name and description
Color palette
Typography settings
Tone and voice guidelines
Imagery preferences

Available Resources

post://{postId}

Access post data as an MCP resource.

Example URI:

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

preview://{postId}/{platform}

Get platform-specific preview content.

Example URI:

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

Development

Building

pnpm build

Running Locally

pnpm start -- --api-key YOUR_API_KEY

Type Checking

pnpm typecheck

Development Mode (Watch)

pnpm dev

API Integration

The MCP server connects to Thoth's REST API endpoints:

POST /api/v1/posts - Create new posts
GET /api/v1/posts/{postId} - Retrieve single post
GET /api/v1/posts - List posts with pagination
PUT /api/v1/posts/{postId} - Update existing post
GET /api/v1/brand-styles - List brand styles
GET /api/v1/brand-styles/{brandStyleId} - Get brand style details

All requests require the X-API-Key header for authentication.

Error Handling

The server provides detailed error messages for common issues:

Invalid API Key: Check your API key is correct and active
Rate Limit Exceeded: Wait before making additional requests
Post Not Found: Verify the post ID is correct
Invalid Parameters: Check parameter types and formats
Network Errors: Verify the base URL and network connection

Examples

Creating a Multi-Platform Post

// Using the create-post tool
{
  "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
}

Scheduling a Post

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

Retrieving Post Data

// Using the get-post tool
{
  "postId": "123e4567-e89b-12d3-a456-426614174000"
}

Accessing Resources

// Read post resource
{
  "uri": "post://123e4567-e89b-12d3-a456-426614174000"
}

// Read platform-specific preview
{
  "uri": "preview://123e4567-e89b-12d3-a456-426614174000/twitter"
}

Testing HTTP Mode Locally

Start the server in HTTP mode:

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

Test the health endpoint:

curl http://localhost:8081/health

Test the MCP endpoint with MCP Inspector:

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

Or use with a Streamable HTTP MCP client that supports query-based configuration.

Troubleshooting

Server won't start

Check that you have Node.js 18+ installed
Verify your API key is valid
Ensure the base URL is correct and accessible

Tool calls fail

Verify your API key has the required permissions
Check rate limits haven't been exceeded
Ensure post IDs are valid UUIDs
Verify platform names are spelled correctly

HTTP mode not accessible

Check the port isn't already in use: lsof -i :8081 (or your configured PORT)
Verify firewall settings allow the connection
Ensure the server process is running with the --remote flag
Check the server logs for any startup errors
Verify the /health endpoint responds: curl http://localhost:8081/health
For Smithery deployments, check the deployment logs in the Smithery dashboard

Smithery deployment fails

Ensure your GitHub repository is public or connected to Smithery
Verify smithery.yaml and Dockerfile are in the repository root
Check the build logs in Smithery dashboard for specific errors
Ensure all dependencies are declared in package.json
Try building the Docker image locally: docker build -t thoth-mcp .

Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Please ensure your code:

Follows the existing TypeScript style
Includes appropriate Zod schemas for validation
Updates documentation as needed
Passes type checking (pnpm typecheck)
Uses console.error() for logging (not console.log() - it breaks stdio mode)

For Maintainers

See PUBLISHING.md for detailed instructions on building and publishing updates.

Support

Smithery: https://smithery.ai/ (One-click deployment)
MCP Registry: https://registry.modelcontextprotocol.io/servers/io.github.zeiq-co/thoth-mcp
npm Package: https://www.npmjs.com/package/@usethoth/mcp-server
Documentation: https://docs.usethoth.com
Issues: https://github.com/perminder-klair/thoth-mcp/issues
API Reference: https://docs.usethoth.com/api

License

MIT License - see the LICENSE file for details.

Changelog

v1.3.0 (2025-10-10)

NEW: Added official Claude Code plugin
NEW: 5 slash commands for streamlined content workflows
NEW: 3 specialized AI agents (Content Creator, Brand Manager, Social Media Optimizer)
Plugin provides user-friendly interface to all MCP server capabilities
Comprehensive plugin documentation and usage examples
Enhanced developer experience for Claude Code users

v1.2.0 (2025-10-08)

NEW: Added HTTP transport support for Smithery and cloud deployments
NEW: Implemented MCP Streamable HTTP with /mcp and /health endpoints
Server now supports dual transport modes: stdio (local) and HTTP (remote)
Added Express and CORS dependencies for HTTP server
Added Dockerfile for containerized deployment
Configured for Smithery deployment with proper HTTP runtime
HTTP mode supports configuration via query parameters
Maintains backward compatibility with stdio mode for Claude Desktop

v1.0.3 (2025-10-08)

Added comprehensive publishing documentation (PUBLISHING.md)
Removed all debug console logs from config
Improved contributor guidelines

v1.0.2 (2025-10-08)

CRITICAL FIX: Removed console.log statements breaking stdio JSON-RPC protocol
Changed debug output to stderr to prevent JSON parsing errors
Server now works correctly with Claude Desktop and other MCP clients

v1.0.1 (2025-10-08)

Published to official MCP Registry
Updated package metadata
Complete tool documentation

v1.0.0 (2025-10-08)

Initial release
Support for 6 Thoth API tools
Multi-platform content creation
Brand style integration

thoth-mcp

Quick Install

Thoth MCP Server

Quick Start

Table of Contents

Features

Claude Code Plugin

What is it?

Quick Start with Plugin

Documentation

Installation

Via MCP Registry (Recommended)

Via Smithery (Zero-Setup Deployment)

Global Installation (via npx)

Local Development

Usage

Prerequisites

Running the Server

Stdio Mode (Local)

Remote HTTP Server Mode

Environment Variables

MCP Client Configuration

Claude Desktop

Other MCP Clients

Available Tools

create-post

get-post

get-all-posts

update-post

get-brand-styles

get-brand-style

Available Resources

post://{postId}

preview://{postId}/{platform}

Development

Building

Running Locally

Type Checking

Development Mode (Watch)

API Integration

Error Handling

Examples

Creating a Multi-Platform Post

Scheduling a Post

Retrieving Post Data

Accessing Resources

Testing HTTP Mode Locally

Troubleshooting

Server won't start

Tool calls fail

HTTP mode not accessible

Smithery deployment fails

Contributing

For Maintainers

Support

License

Changelog

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)

Reviews