ToneClone MCP Server

A Model Context Protocol (MCP) server for ToneClone that enables AI tools like Cursor, Claude Desktop, and ChatGPT to write content in your unique voice and style.

Overview

ToneClone MCP Server bridges the gap between AI code editors/chat interfaces and ToneClone's personalized writing AI. It exposes four key tools:

• toneclone_write - Generate content using your trained personas
• toneclone_list_personas - List your available writing personas
• toneclone_list_knowledge_cards - List your knowledge cards for context
• toneclone_submit_training - Submit training text to improve your personas

MCP Compatibility

| Tool | Local (stdio) | Remote (HTTP/SSE) | |------|---------------|-------------------| | Cursor | ✅ Full Support | ⚠️ Not needed | | Claude Desktop | ✅ Full Support | ⚠️ Not needed | | Cline (VS Code) | ✅ Full Support | ⚠️ Not needed | | ChatGPT Developer Mode | ❌ Not supported | ✅ Full Support |

Installation

Prerequisites

• Node.js 18+
• ToneClone API key (Get one here)

Installation Options

Option 1: NPM Package (Recommended)

npm install -g @toneclone/mcp-server

Option 2: From Source

git clone https://github.com/toneclone/mcp-server.git
cd mcp-server
npm install
npm run build

Option 3: Docker

docker run -p 3000:8080 \
  -e TONECLONE_API_KEY=your_key \
  toneclone/mcp-server

Quick Setup

1. Get your API key: - Visit ToneClone API Keys

   • Generate a new API key

2. Configure your MCP client (see Usage section below)

3. Test the connection:

   # If installed via NPM
   npx @toneclone/mcp-server
      
   # If installed from source
   npm start

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | TONECLONE_API_KEY | Your ToneClone API key (required) | - | | TONECLONE_BASE_URL | ToneClone API base URL | https://api.toneclone.ai | | MCP_MODE | Transport mode: stdio or http | stdio | | PORT | Port for HTTP mode | 3000 | | LOG_LEVEL | Logging level: debug, info, warn, error | info |

Getting Your API Key

1. Sign up at app.toneclone.ai
2. Go to Settings → API Keys
3. Create a new API key
4. Copy the key (starts with tc_live_ or tc_test_)

Usage

Local Mode (Cursor, Claude Desktop)

For Cursor (NPM):

// .cursor/config.json
{
  "mcpServers": {
    "toneclone": {
      "command": "npx",
      "args": ["@toneclone/mcp-server"],
      "env": {
        "TONECLONE_API_KEY": "tc_live_your_key_here"
      }
    }
  }
}

For Cursor (From Source):

// .cursor/config.json
{
  "mcpServers": {
    "toneclone": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "TONECLONE_API_KEY": "tc_live_your_key_here"
      }
    }
  }
}

For Claude Desktop (NPM):

// claude_desktop_config.json
{
  "mcpServers": {
    "toneclone": {
      "command": "npx",
      "args": ["@toneclone/mcp-server"],
      "env": {
        "TONECLONE_API_KEY": "tc_live_your_key_here"
      }
    }
  }
}

For Claude Desktop (From Source):

// claude_desktop_config.json
{
  "mcpServers": {
    "toneclone": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "TONECLONE_API_KEY": "tc_live_your_key_here"
      }
    }
  }
}

Remote Mode (ChatGPT Developer Mode)

1. Start HTTP server:

   npm run start:http

2. Configure ChatGPT:

   • Enable Developer Mode in ChatGPT
   • Add MCP server URL: http://your-server:3000/sse

3. For self-hosting:

   # Deploy to your server
   docker build -t toneclone-mcp .
   docker run -p 3000:8080 -e TONECLONE_API_KEY=your_key toneclone-mcp

Tool Reference

toneclone_write

Generate content using your trained personas.

Parameters:

• prompt (required): The writing prompt or instruction
• personaId (optional): Specific persona to use (defaults to first available)
• knowledgeCardIds (optional): Array of knowledge card IDs for context
• context (optional): Additional context for the writing task
• streaming (optional): Enable real-time streaming (default: false)

Example:

// Write a professional email
await toneclone_write({
  prompt: "Write a follow-up email about the project proposal",
  knowledgeCardIds: ["email-template-card"],
  context: "This is for a client meeting next week"
});

toneclone_list_personas

List all your available writing personas.

Parameters: None

Returns:

{
  personas: [
    {
      personaId: "uuid",
      name: "Professional Writer",
      trainingStatus: "completed",
      smartStyle: true
    }
  ]
}

toneclone_list_knowledge_cards

List your knowledge cards (context profiles).

Parameters: None

Returns:

{
  knowledgeCards: [
    {
      profileId: "uuid",
      name: "Email Templates",
      instructions: "Write professional emails with proper formatting..."
    }
  ]
}

toneclone_submit_training

Submit training text to improve a persona.

Parameters:

• personaId (required): Target persona UUID
• content (required): Training text content
• filename (optional): Descriptive filename

Example:

await toneclone_submit_training({
  personaId: "your-persona-uuid",
  content: "Here's a sample of my writing style...",
  filename: "writing-sample.txt"
});

Development

Building from Source

# Install dependencies
npm install

# Build TypeScript
npm run build

# Development mode with watch
npm run dev

# Start in stdio mode (default)
npm start

# Start in HTTP mode
npm run start:http

Testing

# Run tests
npm test

# Test with real API
npm start
# In another terminal, test the tools

Project Structure

mcp-server/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── client/
│   │   └── toneclone.ts      # ToneClone API client
│   ├── tools/
│   │   ├── write.ts          # Content writing tool
│   │   ├── personas.ts       # Persona listing tool
│   │   ├── knowledge-cards.ts # Knowledge card listing tool
│   │   └── training.ts       # Training submission tool
│   └── types/
│       ├── api.ts            # API types
│       └── mcp.ts            # MCP-specific types
├── Dockerfile                # Container configuration
└── README.md

Deployment

Self-Hosting

Docker:

docker build -t toneclone-mcp .
docker run -p 3000:8080 \
  -e TONECLONE_API_KEY=your_key \
  -e MCP_MODE=http \
  toneclone-mcp

Manual:

npm run build
MCP_MODE=http npm start

ToneClone Hosted (Coming Soon)

We're working on a hosted version at https://mcp.toneclone.ai for easy ChatGPT integration.

Troubleshooting

Common Issues

"Invalid API key" error:

• Verify your API key is correct
• Check that the key starts with tc_live_ or tc_test_
• Ensure the key is active in your ToneClone account

"Network error" when connecting:

• Check your internet connection
• Verify TONECLONE_BASE_URL is correct
• Try the health check: curl https://api.toneclone.ai/ping

Tools not appearing in Cursor/Claude:

• Restart the MCP client (Cursor/Claude Desktop)
• Check the configuration file syntax
• Verify the path to dist/index.js is correct
• Check logs for error messages

Streaming not working:

• Ensure your MCP client supports streaming
• Try with streaming: false first
• Check network connectivity for real-time responses

Debug Mode

Enable debug logging:

LOG_LEVEL=debug npm start

Health Check

For HTTP mode:

curl http://localhost:3000/health

Examples

Writing a Blog Post

// List available personas
const personas = await toneclone_list_personas();

// Write with your preferred persona
const content = await toneclone_write({
  prompt: "Write a blog post about the future of AI in software development",
  personaId: personas.personas[0].personaId,
  knowledgeCardIds: ["tech-writing-card"],
  context: "Target audience: software developers, 800-1000 words"
});

Improving Your Persona

// Submit training content
await toneclone_submit_training({
  personaId: "your-persona-uuid",
  content: `Here's an example of my writing style:

I believe that technology should serve humanity, not the other way around. 
When we build software, we're not just writing code - we're creating tools 
that will shape how people work, communicate, and live their lives.

The best solutions are often the simplest ones. Complexity is easy; 
simplicity is hard. But when we get it right, the results speak for themselves.`,
  filename: "writing-philosophy.txt"
});

Email Generation

// List knowledge cards for context
const cards = await toneclone_list_knowledge_cards();

// Generate professional email
const email = await toneclone_write({
  prompt: "Write a follow-up email after a client meeting",
  knowledgeCardIds: [cards.knowledgeCards.find(c => c.name.includes('Email')).profileId],
  context: "Meeting was about Q4 project timeline, client seemed positive"
});

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

• Documentation: toneclone.ai
• Issues: GitHub Issues
• Email: [email protected]

License

MIT License - see LICENSE file for details.