Thoth MCP Server

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

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: 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:

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

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