Postiz MCP Server & CLI

A Model Context Protocol (MCP) server and command-line interface for the Postiz social media scheduling API. Both entrypoints share the same tool definitions so that AI assistants and human operators can manage social media posts across multiple platforms with identical capabilities.

Features

• Command-line interface: postiz binary with --help output designed for humans and LLMs
• Get Channels: List available social media integrations
• Upload Files: Upload images and media for posts
• List Posts: Query posts with date range filtering
• Create Posts: Create draft, scheduled, or immediate posts
• Update Posts: Modify existing posts
• Delete Posts: Remove posts
• Generate Videos: AI video generation with slides or prompts (Beta)

Supported Platforms

Postiz supports posting to: X (Twitter), LinkedIn, LinkedIn Pages, Reddit, Instagram (Facebook Business), Instagram (Standalone), Facebook Pages, Threads, YouTube, TikTok, Pinterest, Dribbble, Discord, Slack, Mastodon, Bluesky, Lemmy, Warpcast, Telegram, Nostr, VK, Medium, Dev.to, Hashnode, and WordPress.

Installation

1. Clone or download this repository
2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Using the CLI

The CLI and the MCP server share the same environment variables (POSTIZ_API_KEY, POSTIZ_BASE_URL). Configure them once and they will work in both contexts.

Quick test without installation

npx tsx src/cli.ts --help

Install the postiz binary

npm run build
npm_config_prefix="$HOME/.npm-global" npm link   # Or just `npm link` if you have system permissions

Make sure $(npm config get prefix)/bin (e.g. ~/.npm-global/bin) is in your PATH, then run:

postiz --help
postiz posts --start-date 2024-10-01 --end-date 2024-10-07 --pretty

Hot reload during development

npm run dev:cli -- --help

The watcher re-runs the CLI with the same arguments every time you save a file under src/.

Configuration

Environment Variables

Set the variables in your shell profile (~/.zshrc, ~/.bash_profile, etc.) or create a .env file with the following values:

POSTIZ_API_KEY=your_postiz_api_key_here
POSTIZ_BASE_URL=https://api.postiz.com/public/v1  # Optional, defaults to hosted Postiz

Getting Your API Key

1. Log into your Postiz account
2. Go to Settings > API Keys
3. Generate a new API key
4. Copy the key to your .env file

Note: The Postiz API has a rate limit of 30 requests per hour.

Usage with Claude Desktop

Add this to your Claude Desktop configuration file:

Windows

%APPDATA%\Claude\claude_desktop_config.json

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "postiz": {
      "command": "node",
      "args": ["/path/to/postiz-mcp/build/index.js"],
      "env": {
        "POSTIZ_API_KEY": "your_postiz_api_key_here"
      }
    }
  }
}

Available Tools

All commands exposed by the MCP server are available in the CLI. Run postiz --help to see the full list and postiz <tool-name> --help to inspect the parameters (help text is generated automatically from the Zod schema).

postiz-get-channels (CLI: postiz channels)

Get list of available social media channels/integrations.

No parameters required

postiz-upload-file (CLI: postiz upload)

Upload a file for use in posts.

- filePath: string (required) - Path to the file to upload
- filename: string (optional) - Custom filename

postiz-list-posts (CLI: postiz posts)

List posts with date range filtering.

- startDate: string (required) - Start date in YYYY-MM-DD or ISO 8601 datetime (date-only expands to 00:00:00)
- endDate: string (required) - End date in YYYY-MM-DD or ISO 8601 datetime (date-only expands to 23:59:59.999)
- customer: string (optional) - Customer filter

postiz-create-post (CLI: postiz create)

Create a new post.

- content: string (required) - Post text content
- integrations: string[] (required) - Array of channel IDs
- status: 'draft' | 'scheduled' | 'now' (optional, default: 'draft')
- scheduledDate: string (optional) - ISO 8601 date for scheduling
- images: string[] (optional) - Array of image URLs/file IDs

postiz-update-post (CLI: postiz update)

Update an existing post. IMPORTANT: updates are not partial; include the full content again or it will be cleared.

- id: string (required) - Post ID to update
- content: string (optional) - Full content (send all text again, even if unchanged)
- integrations: string[] (optional) - New channel IDs
- status: 'draft' | 'scheduled' | 'now' (optional) - New status
- scheduledDate: string (optional) - New schedule date
- images: string[] (optional) - New images

postiz-delete-post (CLI: postiz delete)

Delete a post.

- id: string (required) - Post ID to delete

postiz-generate-video

Generate AI video (Beta feature).

- slides: object[] (optional) - Array of slide objects with image and text
- prompt: string (optional) - Text prompt for AI generation
- voice: string (optional) - Voice setting
- duration: number (optional) - Duration in seconds

Example Usage (CLI)

# Create an immediate post
postiz create \
  --content "Hello from my AI assistant! 🤖" \
  --integrations twitter_channel_id \
  --integrations linkedin_channel_id \
  --status now

# Schedule a post
postiz create \
  --content "Scheduled post content" \
  --integrations twitter_channel_id \
  --status scheduled \
  --scheduled-date "2024-01-15T10:00:00+01:00"

# Upload an image and reuse it
postiz upload --file-path /path/to/image.jpg --pretty
# Use the returned URL in the --images array when calling `postiz create`

Development

Build

npm run build

Development Mode

# Rebuilds and restarts the MCP server in watch mode
npm run dev

# Iterate on the CLI without rebuilding the output in build/
npm run dev:cli -- --help

Format Code

npm run format

API Rate Limits

Postiz API has a rate limit of 30 requests per hour. The MCP server will handle rate limit errors gracefully and return appropriate error messages.

Self-Hosted Postiz

If you're using a self-hosted Postiz instance, set the POSTIZ_BASE_URL environment variable:

POSTIZ_BASE_URL=https://your-postiz-instance.com/public/v1

Error Handling

All tools return structured JSON responses with:

• success: boolean indicating if the operation succeeded
• error: error message if operation failed
• statusCode: HTTP status code for API errors
• Data fields specific to each operation

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request