Postoria MCP Server

Postoria MCP Server is a universal AI-agent adapter for the Postoria Public API.

It lets MCP-compatible clients create, schedule, queue, inspect, and delete Postoria posts through the public API at https://api.postoria.io/v1.

Distribution model

This repository is the public GitHub source of truth for the MCP server code.

• npm package: @postoria/mcp-server

• Local transport: stdio

• Hosted transport: Streamable HTTP at https://mcp.postoria.io/mcp

• Production deployment: handled separately from GitLab/EKS by installing a pinned npm version into a private deployment image

This repository does not deploy production infrastructure. The hosted mcp.postoria.io deployment should pin a released npm version and be managed from Postoria's GitLab deployment project.

Related MCP server: postiz-mcp

Features

• TypeScript / Node.js implementation

• Local stdio transport for desktop and IDE MCP clients

• Streamable HTTP transport for the hosted endpoint

• Uses only the Postoria Public API, never internal Postoria services or database access

• npm-ready package: @postoria/mcp-server

• MCP Registry metadata in server.json

• Covers all current Postoria Public API v1 endpoints

Supported Postoria API coverage

The low-level Public API POST /posts operation is intentionally exposed through intent-based tools (publish_post_now, schedule_post, and add_post_to_queue) instead of a generic create_post tool, so AI agents have fewer ambiguous choices.

Requirements

• Node.js 20+

• A Postoria Public API key

Local stdio usage

Claude Desktop / Cursor-style config

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

Run locally from source

npm install
POSTORIA_API_KEY=ptr_your_api_key_here npm run dev:stdio

Hosted Streamable HTTP usage

Hosted endpoint:

https://mcp.postoria.io/mcp

Clients should send the Postoria API key as a Bearer token:

Authorization: Bearer ptr_your_api_key_here

Local HTTP development

npm install
POSTORIA_API_KEY=ptr_your_api_key_here npm run dev:http

The server listens on:

http://localhost:3000/mcp

Health check:

http://localhost:3000/health

npm publishing

Update the version in both files before releasing:

• package.json

• server.json

Create a GitHub release with a semver tag, for example:

v1.0.0

The GitHub release workflow publishes @postoria/mcp-server to npm. Required GitHub secret:

Prereleases are published with the npm beta tag. Normal releases are published with the default npm tag.

Production deployment

Production deployment for https://mcp.postoria.io/mcp is intentionally outside this repository.

Recommended Postoria flow:

GitHub release
  -> publishes @postoria/mcp-server@x.y.z to npm

GitLab deploy repo
  -> pins MCP_VERSION=x.y.z
  -> builds a private Docker image from that npm version
  -> pushes it to GitLab Container Registry
  -> deploys it to AWS/EKS

This keeps the public GitHub repo as the source of truth for code, while GitLab remains the source of truth for production deployment state.

MCP Registry

server.json contains both distribution methods:

• remote Streamable HTTP: https://mcp.postoria.io/mcp

• local npm stdio package: @postoria/mcp-server

Update the version in package.json and server.json together before publishing a release.

Security notes

• The MCP server does not store Postoria API keys.

• Local stdio mode reads POSTORIA_API_KEY from the environment.

• Hosted HTTP mode expects Authorization: Bearer <api_key>.

• The server forwards requests to the Postoria Public API.

• 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