@r3lab/x-mcp

A Model Context Protocol (MCP) server for the R3-X app. It lets AI agents (Claude Desktop, Claude Code, Cursor, etc.) manage a company's posts, schedules, personas, platforms, engagement, and analytics through an API key.

Requests are scoped to a company: for a company-scoped key, that's the one company the key was created for; for a master key (see below), it's whichever company you target per call via companyId.

Requirements

• Node.js >= 18
• An X app API key (Settings → API Keys)
• The X app base URL (e.g. https://x.r3lab.dev)

Configuration

The server reads two environment variables:

| Variable | Required | Description | | ----------- | -------- | ---------------------------------------- | | X_API_KEY | yes | API key generated in the app settings. | | X_URL | yes | App base URL, no trailing slash. |

Install into Claude Desktop (.mcpb)

Instead of hand-editing the MCP config, install the bundle: it ships the server plus its dependencies and asks for your settings in a dialog.

# build it (from the repo root)
yarn bundle:mcpb
# -> dist-mcpb/r3lab-x-mcp-0.2.0.mcpb

Double-click the .mcpb (or open it with Claude for macOS/Windows). You'll be prompted for:

| Setting | Notes | | ------- | ----- | | API key | From R3-X → Settings → API keys. Stored securely and masked. A master key manages all your companys. | | URL | Base URL of your instance. Pre-filled with the production default. |

The bundle is self-contained — it does not need npx or a global install.

Usage

Claude Desktop / Cursor

Add to your MCP config (claude_desktop_config.json or equivalent):

{
  "mcpServers": {
    "r3-x": {
      "command": "npx",
      "args": ["-y", "@r3lab/x-mcp"],
      "env": {
        "X_API_KEY": "x_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "X_URL": "https://x.r3lab.dev"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add r3-x \
  --env X_API_KEY=x_xxx \
  --env X_URL=https://x.r3lab.dev \
  -- npx -y @r3lab/x-mcp

Local development

yarn workspace @r3lab/x-mcp build
X_API_KEY=x_xxx X_URL=http://localhost:3000 node packages/x-mcp/dist/index.js

Master keys

An API key is either company-scoped (bound to one company) or master (manages every company owned by the key's owner). Every tool accepts an optional companyId input to target one of those companies on a per-call basis:

• With a master key, pass companyId to select which company the call applies to. Omitting it is only valid for the company-management tools that don't need a target (e.g. x_list_companies, x_create_company).
• With a company-scoped key, companyId is unnecessary — the key already identifies the company — so you can omit it.

Master keys also unlock a set of company-management tools (see below) for listing, creating, updating, and deleting the companies they manage.

Tools

Companies (master keys)

| Tool | Description | | ---------------------- | --------------------------------------------------- | | x_list_companies | List companies (all of them for a master key). | | x_create_company | Create a company (master keys only). | | x_update_company | Update a company's details. | | x_delete_company | Delete a company (master keys only). |

Posts

| Tool | Description | | ----------------- | -------------------------------------------------- | | x_list_posts | List posts (filter by status). | | x_get_post | Get a post by id. | | x_create_post | Create a post (draft by default). | | x_update_post | Update a post. | | x_delete_post | Delete a post. | | x_publish_post | Publish a post immediately to given platforms. |

Schedules

| Tool | Description | | --------------------- | ----------------------------------------------- | | x_list_schedules | List scheduled posts within a date range. | | x_schedule_post | Schedule a post to publish at a future time. | | x_reschedule_post | Change a schedule's publish time. | | x_cancel_schedule | Cancel a scheduled post. |

Personas

| Tool | Description | | ---------------------------------- | ------------------------------------------- | | x_list_personas | List AI content personas. | | x_get_persona | Get a persona by id. | | x_create_persona | Create a persona. | | x_update_persona | Update a persona. | | x_delete_persona | Delete a persona. | | x_trigger_persona_autoschedule | Manually trigger a persona's auto-schedule run. |

Platforms

| Tool | Description | | ------------------------------ | --------------------------------------------------- | | x_list_platforms | List platforms assigned to the company. | | x_list_available_platforms | List all profile-level platforms, flagged assigned. | | x_assign_platform | Assign a platform to the company. | | x_unassign_platform | Unassign a platform from the company. |

Engagement

| Tool | Description | | ------------------------ | ----------------------------------------- | | x_get_inbox | List incoming comments/messages. | | x_get_insights | Fetch engagement insights/metrics. | | x_reply_to_comment | Reply to a comment. | | x_hide_comment | Hide/unhide a comment. |

Analytics & company

| Tool | Description | | ------------------- | ------------------------------------------ | | x_get_analytics | Fetch recent analytics snapshots. | | x_get_company | Fetch the company profile. |

How it works

The server is a thin, stateless client over the X app's API-key REST endpoints (/api/v1/posts, /api/v1/schedules, /api/v1/personas, /api/v1/platforms, /api/v1/engagement, /api/v1/analytics, /api/v1/company, /api/v1/companies). It sends the key in the x-api-key header; when a tool call includes companyId, it's forwarded as the x-company-id header so the app knows which company a master key's request applies to. The app resolves the company scope and records API usage. Logs go to stderr so the stdio JSON-RPC channel stays clean.