Typefully: Social Media Infrastructure for AI Agents

README.md

Typefully: Social Media Infrastructure for AI Agents

Typefully is a writing and scheduling tool for social media, supporting X (Twitter), LinkedIn, Threads, Bluesky, and Mastodon from a single dashboard.

What makes it interesting for developers: Typefully exposes a full API and an MCP server, so AI agents can draft, schedule, and publish social content autonomously. Think of it as the "Stripe for social posting." Your agent handles the content, Typefully handles the delivery.

Note

This is a sample gist showcasing how gists.sh renders different file types. Click through the tabs to see Markdown, JSON, YAML, CSV, ICS, and code highlighting in action.

Why AI Agents Need a Publishing Layer

Most AI agents can generate great content. Few can actually publish it. The gap between "here's a draft" and "it's live on 5 platforms" is surprisingly wide: character limits differ, media handling varies, scheduling rules change, and rate limits apply.

Typefully's API abstracts all of that into a single interface.

What You Can Do

• Draft and publish to X, LinkedIn, Threads, Bluesky, and Mastodon from one API call
• Schedule posts to specific times or Typefully's smart queue slots
• Create threads with per-platform formatting
• Attach media via presigned upload URLs
• Tag and organize drafts for team workflows
• Read analytics to close the feedback loop

MCP Integration

Typefully ships an MCP server that works with Claude, Claude Code, and other MCP-compatible agents. Install it once, and your agent can post to social media without any custom API code.

npx typefully-mcp

Or add it to your Claude Code MCP config directly.

Links

• API Documentation
• MCP Setup Guide
• Changelog
• Typefully

analytics.csv

launch.ics

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Typefully//Events//EN
CALSCALE:GREGORIAN
METHOD:PUBLISH
BEGIN:VEVENT
DTSTART:20260315T170000Z
DTEND:20260315T183000Z
SUMMARY:Typefully API v2 Launch
DESCRIPTION:Join us for the live launch of Typefully API v2.\n\nWe will walk through the new endpoints\, demo the MCP integration\, and show how AI agents can publish to five platforms from a single interface.\n\nAgenda:\n- New API walkthrough\n- MCP live demo with Claude\n- Q&A with the team\n\nRegister: https://typefully.com/launch
LOCATION:Online (Zoom)
URL:https://typefully.com/launch
ORGANIZER;CN=Typefully:mailto:hello@typefully.com
STATUS:CONFIRMED
SEQUENCE:0
END:VEVENT
BEGIN:VEVENT
DTSTART:20260322T160000Z
DTEND:20260322T170000Z
SUMMARY:MCP Office Hours
DESCRIPTION:Open office hours for developers building on Typefully's MCP server.\n\nBring your questions\, share what you've built\, and get live debugging help from the team.\n\nNo registration needed. Just show up.
LOCATION:Online (Discord)
URL:https://typefully.com/community
ORGANIZER;CN=Typefully:mailto:hello@typefully.com
STATUS:CONFIRMED
SEQUENCE:0
END:VEVENT
BEGIN:VEVENT
DTSTART:20260401T170000Z
DTEND:20260401T183000Z
SUMMARY:Building AI Social Agents Workshop
DESCRIPTION:Hands-on workshop: build an AI agent that researches a topic\, writes a thread\, and schedules it across platforms.\n\nYou will need:\n- A Typefully account with API access\n- Claude or another MCP-compatible agent\n- Basic familiarity with shell scripting\n\nWe will provide starter templates and walk through everything step by step.
LOCATION:Online (Zoom)
URL:https://typefully.com/workshop
ORGANIZER;CN=Typefully:mailto:hello@typefully.com
STATUS:CONFIRMED
SEQUENCE:0
END:VEVENT
BEGIN:VEVENT
DTSTART:20260410T180000Z
DTEND:20260410T210000Z
SUMMARY:Typefully Community Meetup - NYC
DESCRIPTION:Our first in-person meetup. Drinks\, demos\, and conversations about the future of AI-powered content.\n\nOpen to creators\, developers\, and anyone curious about where social media tooling is heading.\n\nRSVP: https://typefully.com/nyc-meetup
LOCATION:The Cantor Rooftop\, 142 W 49th St\, New York\, NY
URL:https://typefully.com/nyc-meetup
ORGANIZER;CN=Typefully:mailto:hello@typefully.com
STATUS:CONFIRMED
SEQUENCE:0
END:VEVENT
END:VCALENDAR

platforms.json

{
  "typefully": {
    "version": "2.0",
    "description": "Multi-platform social media publishing infrastructure"
  },
  "platforms": {
    "x": {
      "name": "X (Twitter)",
      "enabled": true,
      "features": {
        "max_characters": 280,
        "threads": true,
        "media": {
          "images": true,
          "videos": true,
          "gifs": true,
          "max_attachments": 4
        },
        "scheduling": true,
        "analytics": true,
        "quote_posts": true,
        "community_posts": true,
        "reply_chains": true
      }
    },
    "linkedin": {
      "name": "LinkedIn",
      "enabled": true,
      "features": {
        "max_characters": 3000,
        "threads": false,
        "media": {
          "images": true,
          "videos": true,
          "gifs": false,
          "max_attachments": 10
        },
        "scheduling": true,
        "analytics": true,
        "company_mentions": true,
        "document_posts": true
      }
    },
    "threads": {
      "name": "Threads",
      "enabled": true,
      "features": {
        "max_characters": 500,
        "threads": true,
        "media": {
          "images": true,
          "videos": true,
          "gifs": true,
          "max_attachments": 10
        },
        "scheduling": true,
        "analytics": false,
        "link_previews": false
      }
    },
    "bluesky": {
      "name": "Bluesky",
      "enabled": true,
      "features": {
        "max_characters": 300,
        "threads": true,
        "media": {
          "images": true,
          "videos": false,
          "gifs": false,
          "max_attachments": 4
        },
        "scheduling": true,
        "analytics": false,
        "custom_feeds": true
      }
    },
    "mastodon": {
      "name": "Mastodon",
      "enabled": true,
      "features": {
        "max_characters": 500,
        "threads": true,
        "media": {
          "images": true,
          "videos": true,
          "gifs": true,
          "max_attachments": 4
        },
        "scheduling": true,
        "analytics": false,
        "content_warnings": true,
        "instance_agnostic": true
      }
    }
  }
}

publish.ts

/**
 * publish.ts - Create and schedule a Typefully draft from the command line
 *
 * Usage:
 *   npx tsx publish.ts "Your post content here"
 *   npx tsx publish.ts "Your post content here" --now
 *   npx tsx publish.ts "Your post content here" --schedule 2026-03-15T09:00:00Z
 *
 * Environment:
 *   TYPEFULLY_API_KEY       - your Typefully API key
 *   TYPEFULLY_SOCIAL_SET_ID - your social set ID (find it via the API)
 */

const API_BASE = "https://api.typefully.com/v1";

const apiKey = process.env.TYPEFULLY_API_KEY;
const socialSetId = process.env.TYPEFULLY_SOCIAL_SET_ID;

if (!apiKey) {
  console.error("Error: TYPEFULLY_API_KEY is not set");
  process.exit(1);
}

if (!socialSetId) {
  console.error("Error: TYPEFULLY_SOCIAL_SET_ID is not set");
  process.exit(1);
}

// Parse CLI arguments
const [content, action, scheduleDate] = process.argv.slice(2);

if (!content) {
  console.error('Usage: npx tsx publish.ts "content" [--now|--schedule ISO_DATE]');
  process.exit(1);
}

// Determine publish timing
let publishAt: string | null = null;
if (action === "--now") {
  publishAt = "now";
} else if (action === "--schedule") {
  if (!scheduleDate) {
    console.error("--schedule requires an ISO 8601 date");
    process.exit(1);
  }
  publishAt = scheduleDate;
}

// Create the draft
const response = await fetch(
  `${API_BASE}/social-sets/${socialSetId}/drafts`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      platforms: {
        x: {
          enabled: true,
          posts: [{ text: content }],
        },
        linkedin: {
          enabled: true,
          posts: [{ text: content }],
        },
      },
      ...(publishAt && { publish_at: publishAt }),
    }),
  },
);

if (!response.ok) {
  const error = await response.text();
  console.error(`Error (${response.status}):`, error);
  process.exit(1);
}

const draft = (await response.json()) as { id: string };

console.log(`Draft created: #${draft.id}`);

if (publishAt === "now") {
  console.log("Status: Publishing immediately");
} else if (publishAt) {
  console.log(`Status: Scheduled for ${publishAt}`);
} else {
  console.log("Status: Saved as draft");
}

console.log(`View: https://typefully.com/drafts/${draft.id}`);

schedule.yaml

# Typefully Content Calendar
# Weekly posting schedule with content themes and queue slots

timezone: America/New_York

queue:
  monday:
    - time: "09:00"
      theme: Industry insights
      platforms: [x, linkedin]
    - time: "13:00"
      theme: Product tips
      platforms: [x, threads, bluesky]

  tuesday:
    - time: "10:00"
      theme: Tutorial or how-to
      platforms: [x, linkedin]
    - time: "15:00"
      theme: Community engagement
      platforms: [x, threads, mastodon]

  wednesday:
    - time: "09:00"
      theme: Feature spotlight
      platforms: [x, linkedin, threads]
    - time: "14:00"
      theme: Behind the scenes
      platforms: [x, bluesky]

  thursday:
    - time: "10:00"
      theme: Case study or data
      platforms: [x, linkedin]
    - time: "16:00"
      theme: Quick tip or thread
      platforms: [x, threads, bluesky, mastodon]

  friday:
    - time: "09:00"
      theme: Weekly roundup
      platforms: [x, linkedin]
    - time: "12:00"
      theme: Fun or casual
      platforms: [x, threads, bluesky]

  saturday:
    - time: "11:00"
      theme: Long-form thread
      platforms: [x]

  sunday: []

content_mix:
  educational: 40%
  product: 25%
  engagement: 20%
  promotional: 15%

guidelines:
  - Always include a hook in the first line
  - Use visuals whenever possible (images boost engagement 2-3x)
  - Tailor copy per platform, never cross-post identical text
  - Reply to comments within the first hour
  - Schedule threads for mornings (highest engagement window)

SKILL.md

name	typefully
description	Create, schedule, and manage social media posts via Typefully
triggers	draft a post schedule a tweet post to social media publish on X share on LinkedIn create a thread
tools	mcp typefully

Typefully Skill

This is a simplified sample. The real, installable skill is at typefully.com/agent-skills.

When the user asks to create, schedule, or manage social media content, use the Typefully MCP tools.

Workflow

1. Get the user's social set using typefully_list_social_sets to find available accounts
2. Check the queue with typefully_get_queue to see existing scheduled posts and open slots
3. Create the draft with typefully_create_draft, configuring each platform appropriately

Platform-Specific Rules

• X/Twitter: 280 character limit per post. Use threads for longer content. Mention with @username.
• LinkedIn: Up to 3,000 characters. Tag companies with @[Company Name](urn:li:organization:ID).
• Threads: 500 character limit. No link previews.
• Bluesky: 300 character limit. Handles auto-detected.
• Mastodon: 500 character limit. Use content warnings when appropriate.

Scheduling

• Use "next-free-slot" to let Typefully pick the optimal time
• Use an ISO 8601 datetime for specific scheduling: "2026-03-15T14:00:00Z"
• Use "now" for immediate publishing

Best Practices

• Always confirm the content with the user before publishing (publish_at: "now")
• Default to saving as draft (omit publish_at) unless the user says "publish" or "post now"
• For multi-platform posts, tailor the content per platform rather than copying the same text
• Attach the share: true flag when the user wants a preview link