PostSider

Open-source social media scheduling for humans, teams, and AI agents.

Schedule and publish across 33 built-in connectors from one calendar.
Self-host with Docker, automate through the REST API and Node.js SDK, or connect AI agents through MCP.

Website · Documentation · Quick Start · MCP · API & SDK

What is PostSider?

PostSider is an open-source social media management and scheduling platform built around four ways of working:

PostSider ships with 33 active connectors registered in the application. You configure credentials only for the platforms you actually use.

AI features are optional. PostSider works without an OpenAI API key.

Quick Start

For a local evaluation, the fastest path is Docker Compose.

Requirements

• Docker
• Docker Compose

Start PostSider

git clone https://github.com/lumizone/postsider.git
cd postsider
docker compose up -d

The default Compose stack pulls:

ghcr.io/lumizone/postsider-app:latest

and starts PostSider with PostgreSQL, Redis, and Temporal.

Open:

http://localhost:4007

Create the first administrator account:

docker exec -it postsider pnpm bootstrap

The bootstrap command prints a one-time password. Sign in with:

admin@setup.local

and the generated password. PostSider then prompts you to set your real email address and password.

The root docker-compose.yaml is convenient for local evaluation. For an internet-facing deployment, use the production setup and the self-hosting guide.

Highlights

Scheduling and publishing

• Visual calendar with drag-and-drop scheduling
• Posting queue and find-free-slot scheduling
• Smart Slot suggestions
• Evergreen content recycling
• Per-platform previews
• Per-platform validation before publishing
• Automatic first comments where supported
• Bulk CSV import

Content workflow

• Hashtag groups
• Caption templates
• Reusable snippets
• UTM builder
• Draft and approval workflows
• Shared media library

Teams and organizations

• Multi-organization workspaces
• Separate workspaces for brands or clients
• Admin and User roles
• Shared publishing workflow

Automation

• Public REST API
• Node.js SDK: @postsider/node
• MCP server: @postsider/mcp
• Webhooks
• Programmatic scheduling and channel access

Optional AI

• Post Checker
• Caption rewriting
• Platform-level OPENAI_API_KEY
• Per-organization bring-your-own key support

Security

• Optional TOTP two-factor authentication
• One-time recovery codes
• Organization-wide 2FA enforcement
• Encrypted provider credentials at rest
• Security activity trail
• Secure httpOnly cookies
• CORS and CSP controls
• Rate limiting
• Server-side authorization and plan enforcement

Supported Platforms

The list below mirrors the active providers registered in:

libraries/nestjs-libraries/src/integrations/integration.manager.ts

That is 33 active connectors in the current integration registry.

You only need OAuth/API credentials for the providers you intend to use. See:

• .env.example
• Channel configuration
• Environment configuration

Mastodon supports custom instances through the standard Mastodon provider.

Adding a provider

Provider integrations live in:

libraries/nestjs-libraries/src/integrations/social/

A new connector typically:

1. Extends SocialAbstract
2. Implements SocialProvider
3. Is registered in socialIntegrationList in integration.manager.ts
4. Adds the corresponding frontend platform metadata/assets

New provider integrations are especially welcome as pull requests.

AI Agents (MCP)

PostSider includes an MCP server for compatible AI clients and agents.

The package is:

@postsider/mcp

The MCP layer is a thin interface over PostSider's public API and exposes 19 tools for workflows such as:

• Listing connected channels
• Reviewing the publishing calendar
• Creating drafts
• Requesting approval
• Uploading media
• Working with scheduled content
• Reading analytics

The intended workflow is read-first and draft-first: an agent can prepare work inside the same PostSider workflow used by humans, while publishing remains a deliberate action.

Build the MCP server

pnpm --filter @postsider/mcp build

For a local/stdio connection, configure:

POSTSIDER_API_KEY
POSTSIDER_API_URL

POSTSIDER_API_URL points the MCP server at the PostSider instance you want to use.

Full MCP documentation:

• apps/mcp/README.md
• Hosted MCP walkthrough

Claude Code plugin

This repository also contains the Claude Code plugin metadata and the postsider-workflow skill.

claude plugin marketplace add lumizone/postsider
claude plugin install postsider@postsider

A safe read-only connection check:

List my connected PostSider channels. Do not create or modify anything.

Public API & SDK

PostSider exposes a public REST API for external applications and automation.

Authenticate with your organization's API key.

Node.js SDK

The published SDK package is:

npm install @postsider/node

Example:

import Postsider from '@postsider/node';

const client = new Postsider(
  'your-api-key',
  'https://your-instance.com'
);

// Schedule a post
await client.post({
  type: 'schedule',
  date: '2025-01-15T10:00:00',
  posts: [
    {
      integration: { id: 'channel-id' },
      value: [{ content: 'Hello!' }],
    },
  ],
});

// List posts
const posts = await client.postList({
  page: 0,
  limit: 20,
});

// List connected channels
const channels = await client.integrations();

The public API is exposed under /public/v1.

Architecture

PostSider is a TypeScript pnpm monorepo.

postsider/
├── apps/
│   ├── backend/          # NestJS REST API
│   ├── orchestrator/     # Temporal workers
│   ├── frontend/         # Next.js dashboard
│   ├── commands/         # CLI/bootstrap utilities
│   ├── sdk/              # @postsider/node
│   └── mcp/              # @postsider/mcp
├── libraries/
│   ├── nestjs-libraries/ # Shared backend, database, integrations
│   └── helpers/          # Shared utilities
├── docker-compose.yaml
├── docker-compose.production.yaml
└── .env.example

Tech stack

Design decisions

Temporal for durable scheduling

Scheduled publishing and token-refresh work run through Temporal workflows so background jobs are not tied to one web-process lifetime.

Provider-based integrations

Each social platform is implemented behind a common provider interface. The active registry lives in integration.manager.ts.

Public API first

External tools can use /public/v1, while Node.js consumers can use @postsider/node.

One codebase for hosted and self-hosted deployments

Optional capabilities are controlled through environment configuration. Billing and AI are not required for a self-hosted installation.

Configuration

Start from the example environment file:

cp .env.example .env

The primary local-development settings are:

For production, set a dedicated ENCRYPTION_KEY as documented in .env.example.

The full reference is maintained in:

• .env.example
• PostSider environment documentation

Storage

Local storage is the default:

STORAGE_PROVIDER=local
UPLOAD_DIRECTORY=./uploads

Cloudflare R2 and MinIO are also supported through environment configuration.

Provider credentials

Social providers have their own API/OAuth settings. You do not need to configure all 33 providers.

Configure only the services you plan to connect.

Self-Hosting

PostSider is designed to run on your own infrastructure.

Two Compose files are included:

The production stack includes the PostSider application, PostgreSQL, Redis, MinIO, Temporal, and supporting services used by the deployment.

For production, use the dedicated guide:

Self-host PostSider

The production Compose file intentionally expects production secrets and deployment-specific values rather than shipping usable defaults.

Local Development

Requirements

• Node.js >=20.17.0 <23.0.0
• pnpm 10.6.x
• PostgreSQL
• Redis

Clone and install:

git clone https://github.com/lumizone/postsider.git
cd postsider
pnpm install

Create your environment file:

cp .env.example .env

Apply database migrations:

pnpm prisma-migrate-deploy

Create the initial admin:

pnpm bootstrap

Start the backend and orchestrator:

pnpm dev

In another terminal, start the frontend:

pnpm dev:frontend

Default development URLs:

Backend:  http://localhost:3000
Frontend: http://localhost:4200

Useful commands

# Backend only
pnpm dev:backend

# Orchestrator only
pnpm dev:orchestrator

# Frontend only
pnpm dev:frontend

# Generate Prisma client
pnpm prisma-generate

# Create a Prisma migration
pnpm prisma-migrate-dev

# Apply migrations
pnpm prisma-migrate-deploy

# Build backend + orchestrator
pnpm build

# Build the Node.js SDK
pnpm build:sdk

Contributing

Contributions are welcome.

Good places to contribute include:

• New provider integrations
• Bug fixes with clear reproduction steps
• Documentation
• Performance improvements
• Automated tests
• Type-safety improvements

Typical workflow:

git checkout -b feature/my-feature
# make changes
pnpm run build:backend

Then open a pull request with a clear explanation of the change.

For provider-specific contribution steps, see CONTRIBUTING.md.

Roadmap

• GitHub Actions CI
• Runtime image published to GHCR
• Public REST API
• Node.js SDK
• MCP server
• Broader automated coverage for core flows
• Enable strictNullChecks across the codebase
• Mobile app
• Plugin system for custom integrations
• Advanced analytics dashboard

Support PostSider

If PostSider is useful to you, consider starring the repository. It helps other developers discover the project.

Bug reports, feature requests, and pull requests are also appreciated.

License

PostSider is licensed under the GNU Affero General Public License v3.0.

You may use, modify, and distribute PostSider under the terms of the AGPL-3.0. If you run a modified version as a network service, the license requires the corresponding source code to be made available to users of that service.

PostSider
Open-source social media scheduling for humans, teams, and AI agents.

Website · Docs · GitHub