> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mallary.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Social Media MCP Server

> Mallary MCP is a remote social media MCP server for AI agents and assistants. Use it to publish, reply, read post analytics and audience counts, manage profiles and settings, list connected platforms, and manage webhooks through Model Context Protocol.

Mallary MCP is a remote social media MCP server for AI assistants, agent workflows, and developer tools that speak Model Context Protocol.

Mallary MCP gives you a structured tool layer over the Mallary platform. Your AI agent can post to social media, upload media, and reply to comments. It can also read analytics and publishing jobs, manage profiles, settings, and webhooks, and list connected platforms. You do not need to build a custom REST client first.

## Start here

> [card] [MCP Overview](https://docs.mallary.ai/mcp-reference/introduction.md)
>
> Start with the transport model, endpoint shape, and base MCP behavior.

> [card] [Authentication](https://docs.mallary.ai/mcp-reference/authentication.md)
>
> Learn how to connect with OAuth or a Mallary API key.

> [card] [Enabled Tools](https://docs.mallary.ai/mcp-reference/tools.md)
>
> See the current Mallary MCP tool names for posting, uploads, comments, analytics,
> profiles, settings, connected platform listing, and webhooks.

> [card] [Runtime Behavior](https://docs.mallary.ai/mcp-reference/behavior.md)
>
> Review preflight, idempotency forwarding, API parity, and error handling
> details.

## Add to Cursor

1. Open Cursor Settings
2. Go to Tools & MCP
3. Click + Add new MCP server
4. Paste the following configuration:

```json theme={null}
{
  "mcpServers": {
    "mallary": {
      "url": "https://mallary.ai/mcp"
    }
  }
}
```

5. Save the configuration.
6. Return to Tools & MCP.
7. When Cursor prompts you, click Connect.
8. Enter your Mallary API key in the browser to complete the OAuth flow.

## Add to Claude Code

> [!NOTE]
>
> The official Mallary Claude Code plugin is under review for publication in the Claude Code plugin directory. While review is pending, you can install it directly from Mallary's GitHub marketplace.

Mallary also provides an official Claude Code plugin that bundles this MCP server with Mallary-specific workflow instructions:

```bash theme={null}
claude plugin marketplace add mallarylabs/claude-code-plugins
claude plugin install mallary@mallary
claude plugin enable mallary@mallary
```

Claude Code asks for your Mallary API key when you enable the plugin.

To connect only the MCP server without the plugin:

1. For Claude Code, run:

```bash theme={null}
claude mcp add --transport http mallary https://mallary.ai/mcp
```

2. Run `/mcp`.
3. Select Authenticate for Mallary to complete the OAuth flow.

## Add to Claude

Mallary is in the Claude Connector Directory. You do not need to add a custom server or paste in an API key.

> [card] [Add to Claude](https://claude.ai/directory/connectors/mallary)
>
> Open Mallary in Claude and add the connector.

1. Click **Add to Claude** above.
2. Sign in to Mallary and allow the connection.
3. [Grant Claude network access to upload files to Mallary's CDN](https://docs.mallary.ai/home/claude.md#photos-and-videos)
4. Ask Claude to use Mallary for your social media work.

> [card] [Mallary for Claude](https://docs.mallary.ai/home/claude.md)
>
> See what Claude can do with Mallary.

## Add to ChatGPT

Mallary is available as a ChatGPT plugin. You do not need to add a custom server or paste in an API key.

> [card] [Add to ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6a712cb183048191994564060b91ef43)
>
> Open Mallary in ChatGPT and install the plugin.

1. Click **Add to ChatGPT** above, then click **Install plugin**.
2. Sign in to Mallary and allow the connection.
3. Start a ChatGPT request with `@Mallary` and say what you want to do.

> [card] [Mallary for ChatGPT](https://docs.mallary.ai/home/chatgpt.md)
>
> See what ChatGPT can do with Mallary.

## Add to Codex

```bash theme={null}
codex mcp add mallary --url https://mallary.ai/mcp
```

Run Codex with `codex`. Codex then prompts you to authenticate with OAuth.

## Add to VSCode

Open the Command Palette (`CMD+Shift+P`) → `MCP: Add Server` and enter:

```
https://mallary.ai/mcp
```

or, add the following to your VSCode dedicated MCP configuration file `mcp.json`:

```json mcp.json theme={null}
{
	"servers": {
		"mallary": {
			"url": "https://mallary.ai/mcp"
		}
	}
}
```

## Add to OpenCode

Add to your `opencode.jsonc`:

```json opencode.jsonc theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mallary": {
      "type": "remote",
      "url": "https://mallary.ai/mcp",
      "oauth": {}
    }
  }
}
```

Then authenticate:

```bash theme={null}
opencode mcp auth mallary
```

## What Mallary MCP does

Mallary MCP exposes the same public publishing surface as the Mallary API through MCP tools.

With Mallary MCP you can:

* create upload URLs
* create and schedule social media posts
* read job status
* list grouped posts
* list comments and post supplied replies on published posts
* delete pending posts
* read analytics
* list connected platforms across Mallary's supported platform set
* list profile IDs with `mallary_list_profiles`
* create and rename connection profiles
* target non-default connection profiles with `profile_id`
* read and update profile settings
* manage webhooks
* disconnect platforms

## Why teams use Mallary MCP

Mallary MCP is useful when you want to connect social publishing directly into:

* AI assistants
* autonomous agent workflows
* IDE agents
* internal AI tooling
* LLM-based operator workflows

A model does not need to compose raw HTTP requests for every task. Instead, you give it a tool surface with clearer actions and safer inputs.

## Base URL

```text theme={null}
https://mallary.ai
```

## Endpoint

Mallary serves MCP at:

```text theme={null}
/mcp
```

Supported methods:

* `POST /mcp`
* `GET /mcp`
* `DELETE /mcp`

## Authentication

OAuth-ready clients should use Mallary's browser sign-in flow. Existing scripts and manual clients can still authenticate with a Mallary API key:

```http theme={null}
Authorization: Bearer <mallary_api_key>
```

Identity is resolved from the API key owner.

## MCP transport and behavior

Mallary exposes a remote MCP server over Streamable HTTP for public API parity.

That means:

* MCP tools route through the existing `/api/v1/*` handlers
* posting logic is not duplicated in a separate MCP-only implementation
* Mallary can return tool responses as event-stream payloads
* `mallary_create_post` runs preflight first by default

## Mallary MCP tools

The current enabled tools are:

* `mallary_create_upload_url`
* `mallary_create_post`
* `mallary_get_job`
* `mallary_attach_tiktok_post_url`
* `mallary_list_posts`
* `mallary_list_comments`
* `mallary_reply_to_comment`
* `mallary_delete_post`
* `mallary_get_analytics`
* `mallary_get_audience`
* `mallary_list_profiles`
* `mallary_create_profile`
* `mallary_rename_profile`
* `mallary_list_platforms`
* `mallary_disconnect_platform`
* `mallary_get_settings`
* `mallary_update_settings`
* `mallary_list_webhooks`
* `mallary_create_webhook`
* `mallary_delete_webhook`

Use `mallary_list_profiles` to find random public profile IDs. Tools that publish, list posts, read comments, read post analytics, read audience counts, list platforms, read settings, update settings, or disconnect platforms accept `profile_id` for non-default connection profiles. Omit it to use the default profile.

## What makes Mallary MCP useful

Mallary MCP is a strong fit when you want an AI workflow to:

* generate content and publish it
* upload images or video before publishing
* read whether a post succeeded or failed
* list previous posts and grouped outcomes
* read analytics snapshots after publishing
* browse analytics for older posts with filters and a next cursor
* read follower and subscriber counts for connected accounts
* register or remove webhooks as part of automation

It gives you one social media tool surface instead of separate per-platform agent integrations.

## Relationship to the Mallary API

Mallary MCP is not a separate product surface with different business rules.

It uses the same underlying platform as the dashboard, REST API, and CLI, which means:

* plan gating still applies
* platform rules still apply
* account identity still comes from the same Mallary user account
* job and analytics behavior stay aligned across product surfaces

When an MCP tool creates posts, any platform-specific posting behavior still comes from the API request model, especially `platform_options`.

The same applies to scheduling. `mallary_create_post` accepts an absolute `scheduled_at`. It also accepts a local `scheduled_at` with a `scheduled_timezone` such as `America/New_York`.

For the exact supported fields and examples by platform, see:

[Platform options reference](https://docs.mallary.ai/api-reference/endpoint/create.md#body-platform-options)

The same is true for media validation.

Examples:

* Threads supports text-only posts, one image, one video, or a 2 to 20 item carousel using supported JPG/JPEG/PNG/WEBP/MP4/MOV media.
* YouTube requires exactly one video.
* YouTube video tags use `platform_options.youtube.tags`.
* YouTube AI-content disclosure uses `platform_options.youtube.containsSyntheticMedia`.
* Video thumbnails use `media[].thumbnail_url` and must point to a Mallary-hosted file URL.
* TikTok video posts require one video, and TikTok photo posts support up to 35 JPEG/WebP images.
* Pinterest requires exactly one image or GIF, or exactly one video.

For the full matrix of platform-specific media rules, see:

[Platform-specific media rules](https://docs.mallary.ai/api-reference/endpoint/create.md#platform-specific-media-rules)

## Plans and accounts

Use MCP with your Mallary plan. Starter is $15/month for 5 total social media accounts, Pro is $29 for 15, and Business is \$95 for 100. Posts are unlimited. Scheduling, analytics, and AI comment replies are included.

X publishing and comments use prepaid credits at cost. Analytics and account lookups do not use credits. See [pricing](https://docs.mallary.ai/home/pricing.md).

Existing customers keep their current terms. Read the authenticated workspace's capabilities and limits when planning actions.

## Error handling

When the underlying API call is not successful, Mallary MCP returns structured errors.

Non-2xx results include fields such as:

* `http_status`
* `code`
* `message`
* `details` when available

These fields help agents and integrations decide whether to retry, ask for missing data, or report a plan or validation error.

## Good fit for Mallary MCP

Mallary MCP is a strong fit if you want:

* social media tools inside an AI assistant
* a clean MCP tool surface instead of raw HTTP orchestration
* the same posting backend used by Mallary itself
* uploads, posting, analytics, and webhooks in one MCP server

## Saved Drafts

Saved drafts are available to all users. Save unfinished posts without a publish date or a publishing job. Read, edit, or delete them, then publish or schedule when ready. A request to save a draft does not authorize publishing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.