Tools reference

This page lists every tool exposed by the Mixpost MCP server, grouped by area. For an overview of how to connect and authenticate, see the MCP Server overview.

Tools at a glance

Tool	Type	What it does
`list-workspaces`	Read	List accessible workspaces — call this first
`get-workspace`	Read	Details and counts for one workspace
`list-accounts`	Read	List connected social accounts
`get-account`	Read	Full details for one account
`list-posts`	Read	List and filter posts
`get-post`	Read	Full details for one post
`create-post`	Write	Create, and optionally schedule or publish, a post
`update-post`	Write	Change a post's content, accounts or tags
`update-post-version`	Write	Update a single content version of a post
`attach-tags-to-post`	Write	Add tags, keeping existing ones
`detach-tags-from-post`	Write	Remove tags from a post
`duplicate-post`	Write	Copy a post as a new draft
`schedule-post`	Write	Schedule for a time, or publish now
`add-post-to-queue`	Write	Queue at the next available slot
`delete-post`	Destructive	Trash or permanently delete a post
`restore-post`	Write	Restore a post from the trash
`list-tags`	Read	List workspace tags
`get-tag`	Read	Details for one tag
`create-tag`	Write	Create a tag
`update-tag`	Write	Update a tag's name or colour
`list-media`	Read	List media library files
`get-media`	Read	Full metadata for one file
`upload-media-by-url`	Write	Add a file to the library from a URL
`get-media-upload-status`	Read	Check a background upload's progress

Common parameters

Two arguments appear across most tools:

Key	Format	Required	Description
`workspace`	string	required	UUID of the workspace to operate on. Obtain it from `list-workspaces`. Required by every tool except `list-workspaces`.
`timezone`	string	optional	IANA timezone (e.g. `America/New_York`) used to interpret input dates and format dates in the response. Defaults to your account timezone, then to UTC.

Write operations (create, update, schedule, delete, etc.) require the token owner to have the Member or Admin role in the workspace. See Roles and permissions.

Workspaces

`list-workspaces`

Read-only. List the workspaces the authenticated user can access, most recently updated first. Call this first — every other tool needs a workspace uuid.

Parameters: none.

Returns: count and a workspaces array of { uuid, name, role }.

`get-workspace`

Read-only. Get details about a single workspace: name, the user's role and approval rights, and the number of connected accounts, posts and members.

Key	Format	Required	Description
`workspace`	string	required	Workspace UUID.
`timezone`	string	optional	Timezone for returned datetimes.

Returns: a workspace object — { uuid, name, created_at, role, can_approve, accounts_count, posts_count, users_count }.

Accounts

`list-accounts`

Read-only. List the social media accounts connected to a workspace. Returns each account's numeric id (used with create-post), name, username, provider and authorization status.

Key	Format	Required	Description
`workspace`	string	required	Workspace UUID.
`provider`	string	optional	Filter by provider identifier, e.g. `twitter`, `facebook_page`, `linkedin`.
`authorized_only`	boolean	optional	When `true`, return only accounts whose authorization is still valid.

Returns: count and an accounts array of { id, name, username, provider, authorized }.

`get-account`

Read-only. Get full details for a single connected account by its numeric id, including profile image, external profile URL and provider-specific data (e.g. follower metrics).

Key	Format	Required	Description
`workspace`	string	required	Workspace UUID.
`account_id`	integer	required	Numeric id of the account. Obtain it from `list-accounts`.
`timezone`	string	optional	Timezone for returned datetimes.

Returns: an account object — { id, uuid, name, suffix, username, provider, provider_name, authorized, image, external_url, data, created_at }.

Posts

`list-posts`

Read-only. List posts in a workspace, most recent first, with optional filters. Returns a compact summary per post: uuid, status, schedule/publish/created times, accounts, tags, plain-text content and media count.

Key	Format	Required	Description
`workspace`	string	required	Workspace UUID.
`status`	string	optional	One of `draft`, `scheduled`, `published`, `failed`, `needs_approval`, `trash`.
`account_ids`	array<integer>	optional	Only posts assigned to any of these account ids.
`tag_ids`	array<integer>	optional	Only posts tagged with any of these tag ids.
`keyword`	string	optional	Only posts whose content contains this text.
`scheduled_from`	string	optional	Only posts scheduled at or after this UTC date/time. Format `Y-m-d` or `Y-m-d H:i`.
`scheduled_to`	string	optional	Only posts scheduled at or before this UTC date/time. A date-only value includes the whole day.
`created_from`	string	optional	Only posts created at or after this UTC date/time.
`created_to`	string	optional	Only posts created at or before this UTC date/time.
`limit`	integer	optional	Maximum number of posts to return (1–100). Defaults to `25`.
`timezone`	string	optional	Timezone for returned datetimes.

Returns: count and a posts array of post summaries (see Post summary shape).

`get-post`

Read-only. Get full details for a single post by its uuid: status, schedule/publish times, author, tags, the accounts it targets (with live post URLs and any publish errors) and every content version with media.

Key	Format	Required	Description
`workspace`	string	required	Workspace UUID.
`uuid`	string	required	UUID of the post. Obtain it from `list-posts`.
`timezone`	string	optional	Timezone for returned datetimes.

Returns: a post object with author, tags, per-account publish info (external_url, errors) and the full versions array.

`create-post`

Writes data. Create a post and optionally schedule or publish it. Provide simple content for a single-version post, or versions for per-account content.

Key	Format	Required	Description
`workspace`	string	required	Workspace UUID.
`account_ids`	array<integer>	required	Numeric IDs of the connected accounts to post to (at least one). Obtain them from `list-accounts`.
`content`	string	optional	The text body, used as the default for every account. Required unless `versions` is given.
`schedule`	string	optional	`draft` (default), `now` (publish immediately), `scheduled` (publish at `scheduled_at`), or `queue` (next slot).
`scheduled_at`	string	optional	When to publish, format `Y-m-d H:i` (e.g. `2026-05-22 14:30`). Required when `schedule` is `scheduled`.
`tags`	array<integer>	optional	Numeric tag IDs to attach. Obtain them from `list-tags`.
`versions`	array	optional	Per-account content versions (see Versions).
`timezone`	string	optional	Timezone for `scheduled_at` and returned datetimes.

Returns: a message, the created post summary, and the timezone used.

`update-post`

Writes data. Update an existing post's content (content or versions), target accounts and/or tags. Only the fields you provide change, and the schedule is left untouched — use schedule-post for timing. The post must not already be published, failed or publishing.

Key	Format	Required	Description
`workspace`	string	required	Workspace UUID.
`uuid`	string	required	UUID of the post. Obtain it from `list-posts`.
`content`	string	optional	New text body. Replaces the body of the post's original content.
`account_ids`	array<integer>	optional	Replace the targeted accounts with these account ids (at least one).
`tags`	array<integer>	optional	Replace the post's tags. Pass an empty array to remove all tags.
`versions`	array	optional	Per-account content versions (see Versions).
`timezone`	string	optional	Timezone for returned datetimes.

Returns: a message, the updated post summary, and the timezone used.

`update-post-version`

Writes data. Update a single content version of a post, leaving the others untouched. Target the original/default version with account_id 0, or an account id to update (or create) that account's version. To replace every version at once, use update-post.

Key	Format	Required	Description
`workspace`	string	required	Workspace UUID.
`uuid`	string	required	UUID of the post. Obtain it from `list-posts`.
`account_id`	integer	required	`0` for the original/default version, or a connected account id for that account's version.
`content`	array	required	Ordered content items for this version (at least one); more than one publishes a thread.
`options`	object	optional	Per-provider post options, keyed by provider identifier (e.g. `{ "mastodon": { … } }`).
`timezone`	string	optional	Timezone for returned datetimes.

Each item in content has body (string), media (array of media ids) and url (string), all optional.

Returns: a message, the updated post summary, and the timezone used.

`attach-tags-to-post`

Writes data. Attach one or more tags to a post, keeping any tags it already has. To replace a post's tags instead, use update-post.

Key	Format	Required	Description
`workspace`	string	required	Workspace UUID.
`uuid`	string	required	UUID of the post. Obtain it from `list-posts`.
`tag_ids`	array<integer>	required	Tag ids to attach (at least one), kept in addition to existing tags.
`timezone`	string	optional	Timezone for returned datetimes.

Returns: a message and the updated post summary.

`detach-tags-from-post`

Writes data. Remove one or more tags from a post, leaving its other tags in place.

Key	Format	Required	Description
`workspace`	string	required	Workspace UUID.
`uuid`	string	required	UUID of the post. Obtain it from `list-posts`.
`tag_ids`	array<integer>	required	Tag ids to remove (at least one).
`timezone`	string	optional	Timezone for returned datetimes.

Returns: a message and the updated post summary.

`duplicate-post`

Writes data. Duplicate an existing post. Creates a new draft copy with the same accounts, tags and content versions; the copy is never scheduled or published.

Key	Format	Required	Description
`workspace`	string	required	Workspace UUID.
`uuid`	string	required	UUID of the post to duplicate.
`timezone`	string	optional	Timezone for returned datetimes.

Returns: a message and the new draft post summary.

`schedule-post`

Writes data. Schedule an existing post for a specific date/time, or publish it immediately with post_now. The post must have at least one account, a future scheduled time, and must not already be published, failed or publishing.

Key	Format	Required	Description
`workspace`	string	required	Workspace UUID.
`uuid`	string	required	UUID of the post. Obtain it from `list-posts`.
`scheduled_at`	string	optional	When to publish, format `Y-m-d H:i`. Required unless `post_now` is `true` or the post already has a scheduled time.
`post_now`	boolean	optional	When `true`, publish immediately instead of scheduling.
`timezone`	string	optional	Timezone for `scheduled_at` and returned datetimes.

Returns: a message and the updated post summary. If the workspace requires approval, the post becomes needs_approval; otherwise it is queued for publishing.

`add-post-to-queue`

Writes data. Add an existing post to the posting queue — it is scheduled at the next available slot of the workspace's posting schedule. The post must have at least one account and must not already be published, failed or publishing.

Key	Format	Required	Description
`workspace`	string	required	Workspace UUID.
`uuid`	string	required	UUID of the post. Obtain it from `list-posts`.
`timezone`	string	optional	Timezone for returned datetimes.

Returns: a message and the updated post summary. The workspace must have posting schedule times configured.

`delete-post`

Destructive. Delete a post. By default it is moved to the trash and can be restored; set permanent to true to delete it irreversibly. Use delete_mode to also remove the published post from the connected social platforms.

Key	Format	Required	Description
`workspace`	string	required	Workspace UUID.
`uuid`	string	required	UUID of the post. Obtain it from `list-posts`.
`delete_mode`	string	optional	`app_only` (default), `social_only`, or `app_and_social`.
`permanent`	boolean	optional	When `true`, permanently delete instead of moving to trash. Only applies when removing from Mixpost. Defaults to `false`.

Returns: a message and the deleted post's uuid.

`restore-post`

Writes data. Restore a post from the trash. The post is recovered as a draft. Only posts moved to the trash (not permanently deleted) can be restored. Find them with list-posts using status: "trash".

Key	Format	Required	Description
`workspace`	string	required	Workspace UUID.
`uuid`	string	required	UUID of the trashed post.
`timezone`	string	optional	Timezone for returned datetimes.

Returns: a message and the restored post summary.

Media

`list-media`

Read-only. List the media files (images, GIFs and videos) in a workspace's library, newest first. Returns each file's numeric id (which can be attached to a post version), name, type and URL.

Key	Format	Required	Description
`workspace`	string	required	Workspace UUID.
`type`	string	optional	Filter by `image`, `gif`, or `video`.
`limit`	integer	optional	Maximum number of files to return (1–100). Defaults to `50`.
`timezone`	string	optional	Timezone for returned datetimes.

Returns: count and a media array of summaries — { id, uuid, name, type, mime_type, url, alt_text, created_at }.

`get-media`

Read-only. Get the full metadata for a single media file by its uuid.

Key	Format	Required	Description
`workspace`	string	required	Workspace UUID.
`uuid`	string	required	UUID of the media file. From `list-media`.
`timezone`	string	optional	Timezone for returned datetimes.

Returns: a media object — { id, uuid, name, type, mime_type, url, thumb_url, alt_text, source, … }.

`upload-media-by-url`

Writes data. Upload a media file to the library by downloading it from a public URL. Small files are downloaded immediately and returned; large files download in the background and appear in list-media once complete.

Key	Format	Required	Description
`workspace`	string	required	Workspace UUID.
`url`	string	required	Publicly accessible URL of the media file to download.
`alt_text`	string	optional	Alternative text describing the media (max 255 characters).
`timezone`	string	optional	Timezone for returned datetimes.

Returns: for a small file, a message and the uploaded media. For a large file, a message, status: "pending" and a download_id — poll it with get-media-upload-status.

`get-media-upload-status`

Read-only. Check the progress of a background media download started by upload-media-by-url.

Key	Format	Required	Description
`workspace`	string	required	Workspace UUID.
`download_id`	string	required	The `download_id` returned by `upload-media-by-url` for a large file.
`timezone`	string	optional	Timezone for returned datetimes.

Returns: while in progress, a status (pending, downloading, processing) and a progress percentage; on completion, status: "completed" and the uploaded media; on failure, an error message.

Provider identifiers

The provider value on an account — and the provider filter on list-accounts — uses these identifiers:

Identifier	Platform
`twitter`	X (Twitter)
`facebook_page`	Facebook Page
`instagram`	Instagram (via a Facebook Page)
`instagram_standalone`	Instagram (standalone)
`threads`	Threads
`linkedin`	LinkedIn (profile)
`linkedin_page`	LinkedIn Page
`tiktok`	TikTok
`pinterest`	Pinterest
`youtube`	YouTube
`gbp`	Google Business Profile
`mastodon`	Mastodon
`bluesky`	Bluesky
`pixelfed`	Pixelfed

Versions

The create-post, update-post and update-post-version tools support per-account content versions, so a single post can have different text or media for each network. The structure mirrors the REST API's post versions:

{
  "versions": [
    {
      "account_id": 0,
      "content": [
        {
          "body": "This is the default content used for every account.",
          "media": [1],
          "url": null
        }
      ],
      "options": {
        "mastodon": { "sensitive": false }
      }
    },
    {
      "account_id": 12,
      "content": [
        { "body": "A custom version just for this account." }
      ]
    }
  ]
}

Key	Format	Required	Description
`versions.*.account_id`	integer	required	The account this version targets. Use `0` for the original/default version. Exactly one version must use `0`.
`versions.*.content`	array	required	Ordered content items. Provide more than one to publish a thread.
`versions..content..body`	string	optional	The text body of this content item.
`versions..content..media`	array<integer>	optional	Media IDs to attach. Obtain them from `list-media` or `upload-media-by-url`.
`versions..content..url`	string	optional	A URL associated with the content (supported by Facebook and LinkedIn).
`versions.*.options`	object	optional	Options available for each social service provider: { "facebook_page": { "type": "post" // post,reel,story }, "instagram": { "type": "post" // post,reel,story }, "linkedin": { "visibility": "PUBLIC" // PUBLIC,CONNECTIONS }, "mastodon": { "sensitive": false // boolean }, "pinterest": { "link": null, // null\|string "title": "", // string "boards": { "account-1": "971672010430333260" // string \| The key `account-` is the ID of your Pinterest account } }, "youtube": { "title": null', // null\|string "status": "public" // public,private,unlisted }, "gbp": { // Google Business Profile "type": "post", // post,offer,event "button": "NONE", // NONE,BOOK,ORDER,SHOP,LEARN_MORE,SIGN_UP,CALL "button_link": "", // string \| Leave empty if button is `NONE` or `CALL` "offer_has_details": false, // boolean \| Only applies if type is `offer` "coupon_code": "", // string \| Only applies if type is `offer` and `offer_has_details` is true "offer_link": "", // string \| Only applies if type is `offer` and `offer_has_details` is true "terms": "", // string \| Only applies if type is `offer` and `offer_has_details` is true "event_title": "", // string \| Only applies if type is `event` or `offer` "start_date": null, // null\|string \| Only applies if type is `event` or `offer` "end_date": null, // null\|string \| Only applies if type is `event` or `offer` "event_has_time": false, // boolean \| Only applies if type is `event` "start_time": "09:00", // string \| Only applies if type is `event` and `event_has_time` is true "end_time": "17:00" // string \| Only applies if type is `event` and `event_has_time` is true } "tiktok": { "privacy_level": { "account-2": 'PUBLIC_TO_EVERYONE' // string \| PUBLIC_TO_EVERYONE,MUTUAL_FOLLOW_FRIENDS,SELF_ONLY \| The key `account-` is the ID of your TikTok account. }, "allow_comments": { "account-2": true // boolean \| The key `account-` is the ID of your TikTok account }, "allow_duet": { "account-2": false // boolean \| The key `account-` is the ID of your TikTok account }, "allow_stitch": { "account-2": false // boolean \| The key `account-` is the ID of your TikTok account }, "content_disclosure": { "account-2": false // boolean \| The key `account-` is the ID of your TikTok account }, "brand_organic_toggle": { "account-2": false // boolean \| The key `account-` is the ID of your TikTok account }, "brand_content_toggle": { "account-2": false // boolean \| The key `account-` is the ID of your TikTok account }, } }

Default version is required

When you provide versions, exactly one must have account_id 0. This is the default content applied to every account that does not have its own account-specific version.

Post summary shape

Most post tools return a compact summary optimised for agents (the heavy web payload is omitted to save tokens):

{
  "uuid": "6059e1b3-e102-4be5-951b-82698abd9ee3",
  "status": "scheduled",
  "scheduled_at": "2026-07-01 09:00:00",
  "published_at": null,
  "created_at": "2026-06-25 14:12:03",
  "accounts": [
    { "id": 12, "name": "Acme", "username": "acme", "provider": "x", "authorized": true }
  ],
  "tags": [
    { "id": 3, "name": "Launch" }
  ],
  "content": "We just shipped a big update 🚀",
  "media_count": 1
}

status is one of draft, scheduled, published, failed, needs_approval, publishing or trash. content is the plain text of the post's original version, with multiple content items joined by blank lines.

Tools reference

Tools at a glance

Common parameters

Workspaces

`list-workspaces`

`get-workspace`

Accounts

`list-accounts`

`get-account`

Posts

`list-posts`

`get-post`

`create-post`

`update-post`

`update-post-version`

`attach-tags-to-post`

`detach-tags-from-post`

`duplicate-post`

`schedule-post`

`add-post-to-queue`

`delete-post`

`restore-post`

Tags

`get-tag`

`create-tag`

`update-tag`

Media

`list-media`

`get-media`

`upload-media-by-url`

`get-media-upload-status`

Provider identifiers

Versions

Post summary shape

On this page

Tools at a glance​

Common parameters​

Workspaces​

list-workspaces​

get-workspace​

Accounts​

list-accounts​

get-account​

Posts​

list-posts​

get-post​

create-post​

update-post​

update-post-version​

attach-tags-to-post​

detach-tags-from-post​

duplicate-post​

schedule-post​

add-post-to-queue​

delete-post​

restore-post​

Tags​

list-tags​

get-tag​

create-tag​

update-tag​

Media​

list-media​

get-media​

upload-media-by-url​

get-media-upload-status​

Provider identifiers​

Versions​

Post summary shape​

On this page

Tools at a glance

Common parameters

Workspaces

`list-workspaces`

`get-workspace`

Accounts

`list-accounts`

`get-account`

Posts

`list-posts`

`get-post`

`create-post`

`update-post`

`update-post-version`

`attach-tags-to-post`

`detach-tags-from-post`

`duplicate-post`

`schedule-post`

`add-post-to-queue`

`delete-post`

`restore-post`

Tags

`list-tags`

`get-tag`

`create-tag`

`update-tag`

Media

`list-media`

`get-media`

`upload-media-by-url`

`get-media-upload-status`

Provider identifiers

Versions

Post summary shape