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.
- Command-line interface:
postizbinary with--helpoutput 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)
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.
- Clone or download this repository
- Install dependencies:
npm install
- Build the project:
npm run build
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.
npx tsx src/cli.ts --helpnpm run build
npm_config_prefix="$HOME/.npm-global" npm link # Or just `npm link` if you have system permissionsMake 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 --prettynpm run dev:cli -- --helpThe watcher re-runs the CLI with the same arguments every time you save a file under src/.
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- Log into your Postiz account
- Go to Settings > API Keys
- Generate a new API key
- Copy the key to your
.envfile
Note: The Postiz API has a rate limit of 30 requests per hour.
Add this to your Claude Desktop configuration file:
%APPDATA%\Claude\claude_desktop_config.json
~/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"
}
}
}
}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).
Get list of available social media channels/integrations.
No parameters required
Upload a file for use in posts.
- filePath: string (required) - Path to the file to upload
- filename: string (optional) - Custom filename
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
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
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
Delete a post.
- id: string (required) - Post ID to delete
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
# 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`npm run build# 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 -- --helpnpm run formatPostiz API has a rate limit of 30 requests per hour. The MCP server will handle rate limit errors gracefully and return appropriate error messages.
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/v1All tools return structured JSON responses with:
success: boolean indicating if the operation succeedederror: error message if operation failedstatusCode: HTTP status code for API errors- Data fields specific to each operation
MIT License - see LICENSE file for details.
- Fork the repository
- Create your feature branch
- Commit your changes
- Push to the branch
- Create a Pull Request