Postoria Server

Postoria MCP Server connects MCP-compatible AI clients to Postoria.

Use it to list workspaces, find social accounts and queues, upload or import media, publish posts, schedule posts, add posts to queues, check post status, and delete posts.

Package

npx -y @postoria/mcp-server

Features

• Local stdio transport for desktop and IDE MCP clients
• Streamable HTTP transport for hosted MCP clients
• Works with Postoria Public API keys
• Supports Postoria workspaces, social accounts, queues, media, and posts
• MCP Registry metadata in server.json

Supported tools

Tool	Description
list_workspaces	List available Postoria workspaces
list_social_accounts	List social accounts in a workspace
list_queues	List queues in a workspace
create_media_upload	Create a signed media upload URL
complete_media_upload	Complete a media upload after raw bytes are uploaded
upload_media_from_file	Upload a local file from stdio clients
import_media_from_url	Import media from a public URL
get_media	Get media status and details
publish_post_now	Publish a post immediately
schedule_post	Schedule a post for a specific time
add_post_to_queue	Add a post to a Postoria queue
list_posts	List posts in a workspace with filters and pagination
get_post	Get post status and details
delete_post	Delete a post created through the Public API

upload_media_from_file is available only in local stdio mode. It is not exposed through the hosted Streamable HTTP endpoint.

Requirements

• Node.js 20+
• A Postoria Public API key for local stdio usage
• A Postoria Public API key or OAuth access token for hosted Streamable HTTP usage

Local stdio usage

Add this to your MCP client configuration:

{
  "mcpServers": {
    "postoria": {
      "command": "npx",
      "args": ["-y", "@postoria/mcp-server"],
      "env": {
        "POSTORIA_API_KEY": "pst_live_your_api_key_here"
      }
    }
  }
}

Hosted Streamable HTTP usage

Hosted endpoint:

https://mcp.postoria.io/mcp

Send an Authorization header on every hosted MCP request. Postoria Public API keys are forwarded to the Public API directly:

Authorization: Bearer pst_live_your_api_key_here

OAuth access tokens accepted by the hosted endpoint are exchanged server-side before calling the Postoria Public API.

OAuth-capable clients discover the authorization server from the protected resource metadata:

https://mcp.postoria.io/.well-known/oauth-protected-resource/mcp

Media upload options

Use import_media_from_url when the media is already available through a public URL.

Use create_media_upload when the client will upload raw file bytes to the returned signed upload URL. After the raw bytes are uploaded with PUT, call complete_media_upload.

Use upload_media_from_file in local stdio mode when the media file exists on the same machine where the MCP server is running.

Run from source

npm install
npm run build

Run in local stdio mode:

POSTORIA_API_KEY=pst_live_your_api_key_here npm run dev:stdio

Run in local HTTP mode:

npm run dev:http

HTTP mode requires the MCP client to send Authorization: Bearer <token> on every /mcp request. POSTORIA_API_KEY is used by local stdio mode only.

Local HTTP endpoint:

http://localhost:3000/mcp

Health check:

http://localhost:3000/health

MCP Registry

server.json includes distribution metadata for:

• remote Streamable HTTP endpoint: https://mcp.postoria.io/mcp
• local npm stdio package: @postoria/mcp-server

Security notes

• The MCP server does not store Postoria API keys.
• Local stdio mode reads POSTORIA_API_KEY from the environment.
• Hosted HTTP mode requires Authorization: Bearer <token> on every MCP request.
• Hosted HTTP mode exchanges OAuth access tokens server-side and does not store refresh tokens.
• POSTORIA_API_KEY is used by local stdio mode only.
• delete_post is destructive and should only be called after user confirmation.

Development

npm install
npm run typecheck
npm run build
npm run format:check