# @xreplyai/mcp

[![npm version](https://img.shields.io/npm/v/@xreplyai/mcp.svg)](https://www.npmjs.com/package/@xreplyai/mcp)
[![npm downloads](https://img.shields.io/npm/dm/@xreplyai/mcp.svg)](https://www.npmjs.com/package/@xreplyai/mcp)
[![license](https://img.shields.io/npm/l/@xreplyai/mcp.svg)](https://www.npmjs.com/package/@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.

The only MCP with **voice profile integration**: post generation is trained on your own archive, not a style prompt, so drafts sound like you, not generic AI.

<!-- TODO(demo): embed a demo GIF here (an agent drafting and scheduling a week of posts from Claude Code). -->

> **Requires a Pro or Team plan.** Every new account gets a **10-day Pro trial** the moment you connect a social account (**no credit card required**), which covers the full MCP toolset.

## Features

37 tools covering the full posts workflow across 15 platforms (X/Twitter, LinkedIn, YouTube, Threads, Instagram, Bluesky, Mastodon, Discord, Slack, Telegram, Facebook, Google Business, Pinterest, TikTok, Tumblr):

- **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
- **Analytics** — Per-account engagement rollups, time series, and best-times-to-post

## Requirements

- Node.js 20+
- An XreplyAI account on a **Pro or Team plan** (or an active 10-day Pro trial) — API keys are a Pro/Team feature. Create one in Settings → API Keys.

## Setup

### Get your API key

Sign in to [XreplyAI](https://xreplyai.com), go to **Settings → API Keys**, and create an API key.

### 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.11.0"],
      "env": {
        "XREPLY_TOKEN": "your-api-key-here"
      }
    }
  }
}
```

### Claude Code

Run this command:

```bash
claude mcp add xreply -e XREPLY_TOKEN=your-api-key-here -- npx @xreplyai/mcp@0.11.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.11.0"],
      "env": {
        "XREPLY_TOKEN": "your-api-key-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=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAeHJlcGx5YWkvbWNwIl0sImVudiI6eyJYUkVQTFlfVE9LRU4iOiJ5b3VyLWFwaS1rZXktaGVyZSJ9fQ)

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

```json
{
  "mcpServers": {
    "xreply": {
      "command": "npx",
      "args": ["@xreplyai/mcp@0.11.0"],
      "env": {
        "XREPLY_TOKEN": "your-api-key-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.11.0"],
      "env": {
        "XREPLY_TOKEN": "your-api-key-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-api-key-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
```

### Remote (hosted) server — no install

Prefer not to run anything locally? XreplyAI also hosts the MCP server over streamable HTTP with OAuth, so there's no `npx` process and no long-lived token to paste. Point any MCP client that supports remote servers at:

```
https://mcp.xreplyai.com/mcp
```

Authentication is OAuth 2.1 against `https://api.xreplyai.com` — your client walks you through sign-in on first connect. (In Claude, add it as a custom connector using that URL.) The same Pro/Team requirement applies.

## 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 posts in your queue — filter by `status`, `source`, `reviewable`; sort by `scheduled_at`/`created_at` (`sort_direction`); paginate with `limit`/`offset` |
| `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_instagram_audio_search` | Search Instagram's audio catalog for a Reel (returns `audio_id`) |
| `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_tumblr_media_upload` | Upload an image for Tumblr (returns r2_key) |
| `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) |
| `xreply_posting_schedule_list` | List posting schedules (one per account) with slots |
| `xreply_posting_schedule_update` | Update one schedule's spacing, timezone, paused state, and slots |

### 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`) |

### Analytics

| Tool | Description |
|------|-------------|
| `xreply_analytics_get` | Read post-performance analytics (read-only). `view: rollups` (default) — per-account totals/averages + followers gained + period-over-period deltas; `view: timeseries` — daily deltas for charting; `view: best_times` — day-of-week × hour engagement grid. Filter with `start_date`/`end_date` (default last 30 days), `social_account_id`, or `platform` |

## 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 API key |
| `XREPLY_POSTHOG_KEY` | No | public project key | PostHog project key for usage analytics. Set to an empty string (`XREPLY_POSTHOG_KEY=""`) to disable analytics entirely |

## Analytics

Each tool call emits a fire-and-forget `$mcp_tool_call` event to PostHog (tool name, server version, duration, and error flag — never argument values). It never blocks or fails the tool response. Opt out by setting `XREPLY_POSTHOG_KEY=""`.

## Development

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