Puter MCP Server

English | 中文

MCP (Model Context Protocol) server for Puter AI media generation. Provides 6 AI-powered tools for image generation, text-to-speech, video generation, OCR, speech-to-text, and voice conversion.

Features

• txt2img: Text-to-image generation with multiple providers (OpenAI, Gemini, Together, xAI, Replicate)

• txt2speech: Text-to-speech conversion with multiple voices and engines

• txt2vid: Text-to-video generation (Sora, Veo, TogetherAI)

• img2txt: Image-to-text (OCR) with AWS Textract or Mistral

• speech2txt: Speech-to-text transcription

• speech2speech: Voice conversion using ElevenLabs

Key Features

• Intelligent Default Models: Automatically selects the best model based on task type

  • Text-to-image: gpt-image-2 (OpenAI)

  • Image-to-image: gemini-2.5-flash-image-preview (Gemini)

• Multiple Providers: Support for OpenAI, Google Gemini, xAI (Grok), Replicate, Together AI, ElevenLabs

• Flexible Output: Supports base64 and URL output formats

• Test Mode: Built-in test mode for development without consuming credits

Quick Start

Prerequisites

• Node.js 18+

• Puter API Key (get from puter.com)

Installation

# Clone the repository
git clone https://github.com/your-username/puter-mcp.git
cd puter-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

1. Copy the environment file:

cp .env.example .env

2. Edit .env and add your Puter API key:

PUTER_API_KEY=your_puter_api_key_here

Usage

Claude Desktop / Trae

Add the following to your Claude Desktop or Trae configuration file:

Windows:

%APPDATA%\Trae\mcp_settings.json

macOS:

~/Library/Application Support/Trae/mcp_settings.json

Linux:

~/.config/Trae/mcp_settings.json

Configuration content:

{
  "mcpServers": {
    "puter-mcp": {
      "command": "node",
      "args": ["path/to/puter-mcp/dist/index.js"],
      "env": {
        "PUTER_API_KEY": "your_api_key"
      }
    }
  }
}

Command Line

# Stdio mode (default)
npm start

# SSE mode
TRANSPORT=sse PORT=3000 npm start

Tools Reference

txt2img

Generate images from text prompts. Supports both text-to-image and image-to-image.

Example:

Generate a picture of a cat

txt2speech

Convert text to speech.

Example:

Convert "Hello world" to speech

txt2vid

Generate videos from text prompts.

Example:

Generate a video of a drone flying over mountains

img2txt

Extract text from images (OCR).

Example:

Extract text from this image: https://example.com/document.png

speech2txt

Convert speech to text.

Example:

Transcribe this audio: https://example.com/speech.mp3

speech2speech

Convert voice to another voice using ElevenLabs.

Example:

Convert this voice to a different voice: https://example.com/speech.mp3

Development

Project Structure

puter-mcp/
├── src/
│   ├── index.ts          # Server entry point
│   ├── client.ts         # Puter SDK initialization
│   ├── utils.ts          # Response formatting utilities
│   ├── puter.d.ts       # TypeScript declarations
│   └── tools/
│       ├── index.ts      # Tool registration
│       ├── txt2img.ts
│       ├── txt2speech.ts
│       ├── txt2vid.ts
│       ├── img2txt.ts
│       ├── speech2txt.ts
│       └── speech2speech.ts
├── scripts/
│   └── verify-responses.ts  # SDK response verification
├── dist/                 # Compiled output
├── package.json
└── tsconfig.json

Build

npm run build

Type Check

npm run typecheck

Development Mode

npm run dev

License

MIT License - see LICENSE for details.

Acknowledgments

• Puter - AI services provider

• MCP SDK - Model Context Protocol

Support

• Issue Tracker: https://github.com/your-username/puter-mcp/issues

• Documentation: https://docs.puter.com/AI/