Thoth MCP

🚀 Thoth MCP Server

The Thoth MCP Server is a Model Context Protocol (MCP) server designed for the Thoth content creation platform. It allows AI assistants and tools to create and retrieve content through Thoth's API, streamlining the content creation process across multiple platforms.

✨ NEW: Claude Code Plugin is now available with slash commands and specialized AI agents, offering a more streamlined content creation workflow!

🚀 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

📚 Table of Contents

• 🚀 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: Supports 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 developed an official Claude Code plugin that simplifies social media content creation with user-friendly commands and specialized AI agents.

What is it?

The Thoth plugin for Claude Code offers:

• 🖱️ 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 - Skilled 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:

1. Visit the Thoth MCP Server on Smithery.
2. Click "Install".
3. Enter your Thoth API key when prompted.
4. 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:

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:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. 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.

📝 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.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.