Buffer MCP

Manage social media using an AI agent - Draft posts, schedule them to 12 social platforms, and check what's coming up right in Claude, ChatGPT, or the other tools you're already in all day.

Hosted MCP Server

npx add-mcp 'https://mcp.buffer.com/mcp'

Installs into Claude Code, Codex, Cursor and more

Documentation

The Model Context Protocol (MCP) is an open standard that lets an AI assistant work with an outside service through a set of tools it can call. Buffer runs a remote MCP server at https://mcp.buffer.com/mcp, which enables AI assistants to read your channels, browse your queue and drafts, schedule and edit posts, capture ideas and pull post analytics, all without leaving the conversation.

Most AI tools connect over OAuth, with no API key. Find yours in Integrations. If it isn't listed, see Other AI tools.

Supported tools

The Buffer MCP server exposes the tools listed below. Each one covers a specific job, like listing channels or scheduling a post, and the server can only do what these tools do. For anything else in Buffer's API, call the GraphQL API directly with an API key, or use the Buffer CLI.

A few conventions apply across the tools:

  • Every ID is a 24-character hex string.
  • Every date and time is an ISO 8601 string with a UTC offset, such as 2026-08-11T17:00:00-05:00. get_account returns the account timezone and its current local time, which is what an assistant should use to turn "tomorrow at 5pm" into a real timestamp.
  • Tools that return lists page with first and after, returning 20 items by default and up to 100 per page.
  • create_post, edit_post, delete_post, create_idea and the template write tools change your data. Most MCP clients ask you to approve those before they run.
  • The write tools hand back the record they saved, and the post tools report each post's allowedActions. An assistant is expected to reuse an ID or a post it has already seen in the conversation rather than spending another call to look the same thing up again.
  • Tool responses carry the quota that is left: the requests remaining in each window and the seconds until it resets. A 429 also reports Retry-After. See the rate limits section below.

Account tools

get_account

Returns the signed-in account and the organizations it belongs to: email, name, timezone, the current time in that timezone, and for each organization its ID, name, plan limits and member count.

If you belong to more than one organization, an assistant will name them and ask which one you mean before going further.

Takes no parameters.

Example prompt: "Which Buffer organizations do I have access to?"

Channel tools

list_channels

Lists the social accounts connected to an organization, with each channel's ID, name, display name, service, type, avatar and connection status.

ParameterTypeRequiredDescription
organizationIdstringYesThe organization to list channels for

Example prompt: "List all my connected Buffer channels."

get_channel

Returns the detail that list_channels leaves out for a single channel: its posting schedule, posting goals, queue status, timezone, link shortening settings, and service-specific data such as Pinterest boards, a Mastodon server URL or Instagram reminder settings.

ParameterTypeRequiredDescription
channelIdstringYesThe channel to read

Example prompt: "What times does my LinkedIn channel post at?"

Post tools

list_posts

Lists posts in an organization. Returns each post's ID, status, text, scheduled and sent times, channel, tags, assets, via and any publishing error.

Each post also carries allowedActions, the list of what you can do with it, so an assistant can move straight to an edit or a delete without reading the post again to find out whether it is allowed.

ParameterTypeRequiredDescription
organizationIdstringYesThe organization to list posts for
channelIdsstring[]NoOnly return posts on these channels
statusstring[]NoAny of draft, needs_approval, scheduled, sending, sent, error
tagIdsstring[]NoOnly return posts carrying any of these tags
dueAtobjectNostart and end bounds on the scheduled time
createdAtobjectNostart and end bounds on the creation time
sortobject[]NoSort by dueAt or createdAt, asc or desc
firstintegerNoPage size, 20 by default and 100 at most
afterstringNoPagination cursor
includeMetricsbooleanNoAlso return per-post analytics. Off by default, since it makes the response much larger

Example prompt: "Show me all my draft posts in Buffer so I can review what's pending."

get_post

Reads one post in full: status, content, author, channel, tags, notes, assets and allowedActions, the list of what you are allowed to do with it. The metadata field carries service-specific data such as Instagram geolocation, a Twitter thread or YouTube privacy settings. A post with the error status carries the failure message.

ParameterTypeRequiredDescription
postIdstringYesThe post to read
includeMetricsbooleanNoAlso return this post's analytics and the time they were last refreshed

Example prompt: "Why did my Instagram post from yesterday fail?"

create_post

Schedules or publishes a post on one channel. Works for Instagram, Facebook, Twitter, LinkedIn, Pinterest, YouTube, Google Business, Mastodon, TikTok, Threads, Bluesky, Substack and Start Page.

What each service needs as a minimum:

  • Twitter, Mastodon, Threads and Bluesky: text only.
  • Facebook: the post type in metadata.facebook.type.
  • Instagram: an image or a video, plus the post type in metadata.instagram.type. A feed post with a single video has to use the reel type, while a story with a single video stays a story.
  • TikTok: an image or a video.
  • Pinterest: an image, plus the board to pin to in metadata.pinterest.boardServiceId, which get_channel returns under metadata.boards[].serviceId.
  • YouTube: a video, plus a title and category in metadata.youtube.
  • Substack: text, an image or a video, or a link in metadata.substack.linkAttachment.
  • Google Business: the post type in metadata.google.type.

Twitter, Mastodon, Threads and Bluesky also take a thread, through metadata.<service>.thread. A threaded post sets both the top-level text and that array, the array holds every item in the thread, and the top-level text repeats the first item's text. Thread items attach media with the same asset shape as the post itself.

A link preview card is not an asset. It goes in metadata.<service>.linkAttachment on Facebook, LinkedIn, Threads and Bluesky, and it cannot be sent alongside a non-empty assets array. On Threads and Bluesky an individual thread item can carry one of its own.

Most posts use automatic scheduling. notification sends you a reminder to publish the post yourself. It is required for Facebook Groups and Instagram personal profiles, and is also available on Instagram, TikTok and YouTube when you ask for a reminder.

ParameterTypeRequiredDescription
channelIdstringYesThe channel to post to, taken from list_channels
schedulingTypestringYesautomatic to publish for you, or notification to send you a reminder to post manually
modestringNoaddToQueue (the default), shareNow, shareNext, or customScheduled, which needs dueAt
textstringNoThe body of the post
dueAtstringNoWhen to publish, required for customScheduled and always in the future
tagIdsstring[]NoTags to file the post under
assetsobject[]NoMedia to attach, each one an image, a video, or a document on LinkedIn
metadataobjectNoService-specific settings, keyed by service
saveToDraftbooleanNoSave as a draft instead of scheduling it
ideaIdstringNoThe idea this post is being created from
draftIdstringNoThe draft this post is being created from

It returns the post it saved: content, assets, service settings, tags, allowedActions, status and scheduling. An assistant does not need to read the post back to confirm what was stored.

Example prompt: "Add a post to my Buffer queue that says 'Excited to share our latest update!' for next Monday."

edit_post

Changes an existing post. The post that results is validated as a whole, the same way a new one is, so anything you do send has to stand on its own rather than being merged field by field into the stored version.

Omission is how you keep what you are not changing, and it is the safer default. Leave assets out and the stored media stays; leave mode and dueAt out and the post keeps its slot; leave a service setting out and it stays as it is. Resending a value you did not mean to change risks writing a stale copy back over something that moved in the meantime.

What has to be complete is any field you do send, because these replace wholesale rather than merging: the assets array, a metadata.<service>.thread array, and a service metadata object, which still has to carry its required members, such as an Instagram post's type and shouldShareToFeed. Dropping one of those from an object you are sending will make the edit fail.

Scheduling follows the same pattern. Leaving schedulingType out keeps the post publishing the way it already does, and leaving mode and dueAt out keeps its current slot. Sending a mode reschedules the post even when it matches the one already set, so send one only when you mean to move the post.

An assistant does not need a fresh read to work this out. create_post and edit_post both return the post they saved, so one that already created or edited the post in this conversation can work from that response, and call get_post only when something it needs is missing or may have gone stale.

When you do replace the media, an existing asset's source becomes url and, on images only, its thumbnail becomes thumbnailUrl; a video never takes a thumbnailUrl and picks its frame through metadata.thumbnailOffset instead, on Instagram, TikTok and Pinterest. Service settings such as firstComment, linkAttachment, an Instagram geolocation and LinkedIn annotations are kept when you leave them out and cleared when you send null.

Editing a threaded post follows the same rule as creating one: send both the top-level text and the whole metadata.<service>.thread array, not just the item that changed.

ParameterTypeRequiredDescription
postIdstringYesThe post to change
schedulingTypestringNoautomatic or notification
modestringNoaddToQueue, shareNow, shareNext, or customScheduled
textstringNoThe body of the post
dueAtstringNoA new publishing time, only valid with customScheduled
tagIdsstring[]NoTags to file the post under
assetsobject[]NoMedia to attach. Leave it out to keep the stored media, send an empty array to clear it, or send a new array to replace it
metadataobjectNoService-specific settings, keyed by service
saveToDraftbooleanNoMove the post back to a draft
ideaIdstringNoThe idea this post is being created from
draftIdstringNoThe draft this post is being created from

It returns the post it saved, in the same shape create_post does.

Example prompt: "Move my Thursday LinkedIn post to Friday at 9am and shorten the opening line."

delete_post

Deletes a post for good. Not every post can be deleted, so an assistant should check that deletePost appears in the post's allowedActions. list_posts and get_post both return that list, so this does not cost an extra lookup.

ParameterTypeRequiredDescription
postIdstringYesThe post to delete

Example prompt: "Delete the draft I made this morning about the pricing update."

get_aggregated_post_metrics

Adds up analytics across many posts over a date range and returns the totals and averages, rather than making an assistant pull every post and do the arithmetic itself.

The response always carries post count, reactions and comments. Other metrics, such as reach, impressions and engagement rate, appear only when every channel in the filter supports them. Metrics refresh once a day, so values can lag the social network by up to a day; metricsUpdatedAt reports how fresh the aggregate is, and is null when no post matched the filter. The date range can cover at most 365 days, and on the Free plan it has to start within the last 31 days.

ParameterTypeRequiredDescription
organizationIdstringYesThe organization to aggregate metrics for
startDateTimestringYesStart of the window, inclusive
endDateTimestringYesEnd of the window, inclusive
channelIdsstring[]NoChannels to include. Leave it out to cover every channel you can see insights for. An empty array filters every channel out and returns an empty result
tagsobjectNoin limits the aggregate to posts carrying any of these tags, isEmpty also counts untagged posts

Example prompt: "How did my LinkedIn posts perform last month?"

Idea tools

list_ideas

Lists the ideas in an organization. Ideas capture a concept for a future post before it belongs to a channel. Each one returns its title, text, media, tags, target services, target date, board column and timestamps.

ParameterTypeRequiredDescription
organizationIdstringYesThe organization to list ideas for
tagIdsstring[]NoOnly return ideas carrying any of these tags
includeUntaggedbooleanNoAlso return ideas with no tags. Off by default
firstintegerNoPage size, 20 by default and 100 at most
afterstringNoPagination cursor

Example prompt: "What ideas do I have saved that are tagged for the product launch?"

list_idea_groups

Lists the columns on the ideas board, with each column's ID, name and lock status.

ParameterTypeRequiredDescription
organizationIdstringYesThe organization to list idea groups for

Example prompt: "What columns does my Buffer ideas board have?"

create_idea

Saves a new idea. This captures content for later. It does not schedule or publish anything.

Idea media can be an image, a GIF, a link or a document. Video is not supported on ideas through the public API.

ParameterTypeRequiredDescription
organizationIdstringYesThe organization to create the idea in
contentobjectYesThe idea itself: title, text, media, tags, target services and a target date, all optional

Example prompt: "Save an idea for a post about our new integration, tagged for Instagram and LinkedIn."

Post template tools

Post templates are reusable starting points for content. A template body can hold {{placeholders}} to fill in later. Each template is public, internal or private: public templates are curated by Buffer, internal ones are shared with everyone in your organization, and private ones are yours alone.

list_post_templates

Lists the templates you can use in an organization. With no filter this returns all three kinds together: the public templates, your organization's internal ones, and your own private ones.

ParameterTypeRequiredDescription
organizationIdstringYesThe organization whose templates to list
visibilitystringNoNarrow to private, internal or public
firstintegerNoPage size, 20 by default and 100 at most
afterstringNoPagination cursor

Example prompt: "What post templates can I use?"

get_post_template

Reads one template: its body, title, description, emoji, visibility and timestamps.

ParameterTypeRequiredDescription
postTemplateIdstringYesThe template to read

Example prompt: "Show me the full text of my product announcement template."

create_post_template

Creates a template in an organization. You can set it to private or internal. Public is curated by Buffer and cannot be set here.

ParameterTypeRequiredDescription
organizationIdstringYesThe organization the template belongs to
titlestringYesThe name of the template
bodystringYesThe content, which may contain {{placeholders}}
descriptionstringYesA short description of what the template is for
emojistringNoAn emoji to show alongside the template
visibilitystringNoprivate, the default, or internal

Example prompt: "Turn this post into a template my whole team can reuse."

update_post_template

Changes a template. Only the fields you send are changed. You can edit templates you own, and internal templates in your organization if you are an admin or owner.

ParameterTypeRequiredDescription
postTemplateIdstringYesThe template to change
titlestringNoThe name of the template
bodystringNoThe content, which may contain {{placeholders}}
descriptionstringNoA short description of what the template is for
emojistringNoAn emoji to show alongside the template
visibilitystringNoprivate or internal

Example prompt: "Add a call to action line to my weekly recap template."

delete_post_template

Deletes a template for good. You can delete templates you own, and internal templates in your organization if you are an admin or owner.

ParameterTypeRequiredDescription
postTemplateIdstringYesThe template to delete

Example prompt: "Delete the old holiday sale template."

Beyond the tools

There is one prompt, review_weekly_posts, which reviews the posts you have scheduled for the current week and groups them by channel. Clients that support prompts usually list it as a command you can pick.

Rate limits

Requests made through the MCP server count against the same rate limits as your API keys: a 15-minute, 24-hour and 30-day window, with quotas that depend on your plan. Your MCP connections and API keys share one set of limits, counted across every request rather than per tool, so one conversation that lists your posts, reads a few of them and then edits one has spent several requests from the same budget.

Tool responses carry the quota alongside the result: the requests remaining in each window and the seconds until that window resets. An assistant can read those numbers and pace itself, rather than finding the limit by hitting it. When less than 10% of a window is left, the response also includes a short note saying you are close to the limit, with a link to raise it when a paid plan would.

Past the limit the call fails with 429 Too Many Requests, and the error the assistant sees carries the Retry-After value from the API, in seconds. That is how long to wait before asking for anything else.

Most of what keeps an assistant inside these limits is how you prompt it. Check out the prompts for AI agents section of the Efficient API Usage guide for best practices and example prompts.

Security considerations

Connecting a client to the MCP server gives it the same reach over your content as you have, so it is worth knowing what that covers before you connect one.

  • The connection covers your whole account. The assistant acts for you and reaches every organization and channel in your account. There is no per-organization scoping, so you cannot open one workspace to an assistant while holding another back.
  • Check the server URL. The only Buffer MCP endpoint is https://mcp.buffer.com/mcp. A one-click install from a third-party list is worth opening and reading before you trust it.
  • Leave the approval prompts on. create_post can publish immediately, and delete_post cannot be undone. Most clients ask before they run a tool that writes, and that prompt is your last chance to catch a misread instruction.

Try It Out

Copy any of these example prompts to get started:

List all my connected Buffer channels

Add a post to my Buffer queue that says 'Excited to share our latest update!' for next Monday

Show me all my draft posts in Buffer so I can review what's pending