# @xreplyai/mcp

MCP server for [XreplyAI](https://xreplyai.com) — plan, generate, and schedule posts in your voice. Manage your post queue and publish to X/Twitter from any AI agent.

## Features

32 tools covering the full posts workflow across 8 platforms:

- **Generation** — Generate single posts, threads, batches, or LinkedIn carousels in your voice
- **Post management** — Create, edit, delete, and list posts
- **Publishing** — Publish immediately, schedule, or queue into the next open posting-schedule slot on any connected platform
- **Media uploads** — Images and video for X, LinkedIn, Instagram, Threads, Bluesky, Pinterest, TikTok, and YouTube
- **Context** — Billing status, voice profile, preferences, platform styles, and custom rules
- **Accounts & communities** — List connected social accounts, X communities, and Pinterest boards

## Requirements

- Node.js 20+
- An XreplyAI account (get your JWT token from Settings)

> **Token expiry:** Tokens expire after 30 days. If the MCP stops authenticating, return to the XreplyAI Settings page, copy a fresh token, and update your MCP config.

## Setup

### Get your token

Sign in to [XreplyAI](https://xreplyai.com), go to **Settings**, and copy your API token.

### 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`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "xreply": {
      "command": "npx",
      "args": ["@xreplyai/mcp@0.4.0"],
      "env": {
        "XREPLY_TOKEN": "your-jwt-token-here"
      }
    }
  }
}
```

### Claude Code

Run this command:

```bash
claude mcp add xreply -e XREPLY_TOKEN=your-jwt-token-here -- npx @xreplyai/mcp@0.4.0
```

Then run `claude mcp list` to confirm it's registered.

Or add manually to `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "xreply": {
      "command": "npx",
      "args": ["@xreplyai/mcp@0.4.0"],
      "env": {
        "XREPLY_TOKEN": "your-jwt-token-here"
      }
    }
  }
}
```

### Cursor

Click to install (you'll be prompted to update your token after):

[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=xreply&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAeHJlcGx5YWkvbWNwIl0sImVudiI6eyJYUkVQTFlfVE9LRU4iOiJ5b3VyLWp3dC10b2tlbi1oZXJlIn19)

Or add manually to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):

```json
{
  "mcpServers": {
    "xreply": {
      "command": "npx",
      "args": ["@xreplyai/mcp@0.4.0"],
      "env": {
        "XREPLY_TOKEN": "your-jwt-token-here"
      }
    }
  }
}
```

### Windsurf

Open Windsurf and go to **Plugins → Manage plugins → View raw config**, then add the server config below. Or edit `~/.codeium/windsurf/mcp_config.json` directly:

```json
{
  "mcpServers": {
    "xreply": {
      "command": "npx",
      "args": ["@xreplyai/mcp@0.4.0"],
      "env": {
        "XREPLY_TOKEN": "your-jwt-token-here"
      }
    }
  }
}
```

### OpenClaw

[OpenClaw](https://openclaw.ai) is a self-hosted AI gateway that connects chat apps (WhatsApp, Telegram, Discord) to AI agents via Skills.

**Install via ClawHub (once published):**

```bash
clawhub install xreply
```

**Manual install:**

```bash
cp -r mcp/openclaw/ ~/.openclaw/skills/xreply/
```

**Configure your token** in `~/.openclaw/openclaw.json`:

```json
{
  "skills": {
    "entries": {
      "xreply": {
        "env": {
          "XREPLY_TOKEN": "your-jwt-token-here"
        }
      }
    }
  }
}
```

The skill uses `mcporter` to bridge OpenClaw to the XreplyAI MCP server. Install it with:

```bash
npm install -g mcporter
```

Verify the skill loads:

```bash
openclaw skills list --eligible
```

## Tools

### Generation

| Tool | Description |
|------|-------------|
| `xreply_posts_generate` | Generate a single post in your voice (all platforms) |
| `xreply_posts_generate_batch` | Generate 1–9 posts at once by category (Personalized/Trending/Viral) |
| `xreply_posts_generate_thread` | Generate a 2–10 tweet X thread in your voice |
| `xreply_carousel_generate` | Generate a LinkedIn PDF carousel (3–12 slides) |

### Post Management

| Tool | Description |
|------|-------------|
| `xreply_posts_list` | List all posts in your queue |
| `xreply_posts_create` | Save a post draft (per-platform content) |
| `xreply_posts_edit` | Edit body, scheduled time, or metadata |
| `xreply_posts_delete` | Delete a post |

### Publishing

| Tool | Description |
|------|-------------|
| `xreply_posts_publish` | Publish now, schedule to a specific time, or queue into the next open posting-schedule slot (`use_next_slot`) |
| `xreply_posts_next_slot` | Preview when a post would go out if queued — returns `scheduled_at` without scheduling anything |

### Media Uploads

| Tool | Description |
|------|-------------|
| `xreply_media_upload` | Upload an image for X or LinkedIn |
| `xreply_video_upload` | Upload a video for LinkedIn |
| `xreply_youtube_upload` | Upload a video for YouTube (presigned R2) |
| `xreply_instagram_media_upload` | Upload an image or video for Instagram |
| `xreply_threads_media_upload` | Upload an image for Threads |
| `xreply_bluesky_media_upload` | Upload an image for Bluesky (returns blob ref) |
| `xreply_pinterest_media_upload` | Upload an image for Pinterest |
| `xreply_linkedin_document_upload` | Upload a PDF for LinkedIn carousels |

### Context & Config

| Tool | Description |
|------|-------------|
| `xreply_billing_status` | Check subscription tier, quota, and limits |
| `xreply_voice_status` | Check voice profile analysis status |
| `xreply_preferences_get` | Get generation preferences (tone, emoji, structure) |
| `xreply_preferences_set` | Update tone, emoji, and structure preferences |
| `xreply_platform_styles_get` | Get per-platform style profiles |
| `xreply_platform_styles_set` | Override style settings for a specific platform |
| `xreply_rules_list` | List custom writing rules (Pro) |
| `xreply_rules_create` | Add a new custom writing rule |
| `xreply_rules_update` | Edit an existing custom writing rule |
| `xreply_rules_delete` | Delete a custom writing rule |
| `xreply_list_social_accounts` | List connected social accounts with IDs |
| `xreply_content_plan_list` | List content plans (automated weekly schedule) |

### Communities & Boards

| Tool | Description |
|------|-------------|
| `xreply_list_twitter_communities` | List recently-used X communities |
| `xreply_pinterest_boards` | List the user's Pinterest boards (with `force_refresh`) |

## Example workflows

### Plan posts for the week

```
1. xreply_posts_generate_batch (category: "personalized", count: 7) — generate 7 posts
2. xreply_posts_list — review the queue
3. xreply_posts_edit (id: X, scheduled_at: "2026-03-10T09:00:00Z") — schedule each
```

### Quick post

```
1. xreply_posts_generate (topic: "my SaaS hit 1000 users", angle: "story_arc")
2. xreply_posts_create (body: "<generated text>")
3. xreply_posts_publish (id: X) — post immediately
```

### Queue to the next open slot

```
1. xreply_posts_create (body: "<post text>") — save a draft
2. xreply_posts_next_slot (id: X) — optional: preview when it would go out
3. xreply_posts_publish (id: X, use_next_slot: true) — queue into the next open posting-schedule slot
```

## Environment variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `XREPLY_TOKEN` | Yes | — | Your XreplyAI JWT token |

## Development

```bash
npm install
npm run build
npm test
XREPLY_TOKEN=your-token npx tsx src/index.ts
```