posterly-mcp-server 0.4.0 → 0.6.0

package/README.md

@@ -0,0 +1,175 @@
+# posterly MCP Server
+
+Use Posterly from any MCP-compatible AI client.
+
+This package gives Claude Desktop, Cursor, Windsurf, Cline, and other local MCP clients a `stdio` server that can:
+
+- list connected social accounts
+- resolve brands/clients into the right accounts
+- schedule and manage posts
+- upload media
+- generate images
+- read account and post analytics
+
+Posterly also exposes the same toolset over HTTP at [poster.ly/mcp](https://www.poster.ly/mcp), but this npm package is the local `stdio` transport.
+
+## Requirements
+
+- Node.js `20+`
+- A Posterly account: [poster.ly/signup](https://www.poster.ly/signup)
+- The Posterly API add-on enabled: [poster.ly/dashboard/api](https://www.poster.ly/dashboard/api)
+- A Posterly API key
+
+## Install
+
+You can install globally:
+
+```bash
+npm install -g posterly-mcp-server
+```
+
+Or just use it via `npx` in your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "posterly": {
+      "command": "npx",
+      "args": ["-y", "posterly-mcp-server"],
+      "env": {
+        "POSTERLY_API_KEY": "pst_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Quick setup
+
+1. Sign up at [poster.ly](https://www.poster.ly/signup)
+2. Go to [Dashboard → API & MCP](https://www.poster.ly/dashboard/api)
+3. Enable the API add-on
+4. Generate an API key
+5. Paste it into your MCP client config as `POSTERLY_API_KEY`
+6. Restart your AI client
+
+## Example configs
+
+### Claude Desktop
+
+Add this to your Claude Desktop MCP config:
+
+```json
+{
+  "mcpServers": {
+    "posterly": {
+      "command": "npx",
+      "args": ["-y", "posterly-mcp-server"],
+      "env": {
+        "POSTERLY_API_KEY": "pst_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add the same server definition to your Cursor MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "posterly": {
+      "command": "npx",
+      "args": ["-y", "posterly-mcp-server"],
+      "env": {
+        "POSTERLY_API_KEY": "pst_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Available tools
+
+`posterly-mcp-server@0.6.0` exposes 16 tools:
+
+- `whoami`
+- `list_accounts`
+- `list_brands`
+- `get_brand`
+- `list_brand_accounts`
+- `get_brand_profile`
+- `list_posts`
+- `get_post`
+- `create_post`
+- `update_post`
+- `delete_post`
+- `upload_media`
+- `find_available_slot`
+- `generate_image`
+- `get_account_analytics`
+- `get_post_analytics`
+
+## What the brand tools are for
+
+Posterly workspaces often have multiple connected accounts under one client or brand.
+
+The brand tools let an assistant work at the same level a human does:
+
+- `list_brands` lets the agent see clients/brands in the workspace
+- `get_brand` returns summary info for one brand
+- `list_brand_accounts` resolves a brand into the actual connected accounts
+- `get_brand_profile` returns saved brand guidance like tone, audience, keywords, dos and don'ts, and visual notes
+
+This makes prompts like:
+
+- "How is Grassroots doing on Instagram?"
+- "Write a post for the Posterly brand voice"
+- "Schedule something for our Dubai dental client"
+
+much more reliable than forcing the agent to guess from raw account handles alone.
+
+## Example prompts
+
+- `What Posterly accounts do I have connected?`
+- `List my brands in Posterly`
+- `Show me the brand profile for Grassroots`
+- `Find the next 3 posting slots for my LinkedIn account`
+- `Schedule a post for tomorrow at 9am for the Posterly Instagram account`
+- `How did Grassroots perform on Instagram in the last 30 days?`
+
+## Pricing
+
+This package uses the Posterly API/MCP add-on:
+
+- `$3/month` add-on
+- `100 requests/hour` per API key
+- works across all 11 supported platforms
+
+Details: [poster.ly/dashboard/api](https://www.poster.ly/dashboard/api)
+
+## Links
+
+- Docs: [poster.ly/mcp](https://www.poster.ly/mcp)
+- OpenClaw skill: [poster.ly/openclaw](https://www.poster.ly/openclaw)
+- API add-on: [poster.ly/dashboard/api](https://www.poster.ly/dashboard/api)
+- MCP server card: [/.well-known/mcp/server-card.json](https://www.poster.ly/.well-known/mcp/server-card.json)
+- OAuth authorization server metadata: [/.well-known/oauth-authorization-server](https://www.poster.ly/.well-known/oauth-authorization-server)
+- OAuth protected resource metadata: [/.well-known/oauth-protected-resource](https://www.poster.ly/.well-known/oauth-protected-resource)
+
+## Development
+
+From the `mcp-server` directory:
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+The package reads:
+
+- `POSTERLY_API_KEY`
+- optional `POSTERLY_URL` if you need to point at a non-production environment

package/dist/index.js

@@ -3,6 +3,10 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { PosterlyClient } from './lib/api-client.js';
 import { listAccountsTool } from './tools/list-accounts.js';
+import { listBrandsTool } from './tools/list-brands.js';
+import { getBrandTool } from './tools/get-brand.js';
+import { listBrandAccountsTool } from './tools/list-brand-accounts.js';
+import { getBrandProfileTool } from './tools/get-brand-profile.js';
 import { createPostTool } from './tools/create-post.js';
 import { findSlotTool } from './tools/find-slot.js';
 import { listPostsTool } from './tools/list-posts.js';
@@ -12,9 +16,11 @@ import { updatePostTool } from './tools/update-post.js';
 import { deletePostTool } from './tools/delete-post.js';
 import { whoamiTool } from './tools/whoami.js';
 import { generateImageTool } from './tools/generate-image.js';
+import { getAccountAnalyticsTool } from './tools/get-account-analytics.js';
+import { getPostAnalyticsTool } from './tools/get-post-analytics.js';
 const server = new McpServer({
     name: 'posterly',
-    version: '0.4.0',
+    version: '0.6.0',
 });
 let client;
 try {
@@ -43,6 +49,42 @@ server.tool(listAccountsTool.name, listAccountsTool.description, listAccountsToo
         return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
     }
 });
+server.tool(listBrandsTool.name, listBrandsTool.description, listBrandsTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await listBrandsTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(getBrandTool.name, getBrandTool.description, getBrandTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await getBrandTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(listBrandAccountsTool.name, listBrandAccountsTool.description, listBrandAccountsTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await listBrandAccountsTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(getBrandProfileTool.name, getBrandProfileTool.description, getBrandProfileTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await getBrandProfileTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
 server.tool(createPostTool.name, createPostTool.description, createPostTool.inputSchema.shape, async (input) => {
     try {
         const text = await createPostTool.execute(client, input);
@@ -115,6 +157,24 @@ server.tool(deletePostTool.name, deletePostTool.description, deletePostTool.inpu
         return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
     }
 });
+server.tool(getAccountAnalyticsTool.name, getAccountAnalyticsTool.description, getAccountAnalyticsTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await getAccountAnalyticsTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(getPostAnalyticsTool.name, getPostAnalyticsTool.description, getPostAnalyticsTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await getPostAnalyticsTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
 // Start the server
 async function main() {
     const transport = new StdioServerTransport();

package/dist/lib/api-client.d.ts

@@ -6,6 +6,41 @@ export interface Account {
     profile_picture_url?: string;
     workspace_id?: string | null;
 }
+export interface Brand {
+    id: string;
+    name: string;
+    workspace_id?: string | null;
+    workspace_client_id?: string | null;
+    legacy_brand_group_id?: string | null;
+    created_at?: string | null;
+    updated_at?: string | null;
+    source: 'canonical' | 'legacy';
+    account_count: number;
+}
+export interface BrandProfile {
+    id: string | null;
+    brand_group_id: string | null;
+    workspace_client_id: string | null;
+    brand_name: string;
+    tone_of_voice?: string | null;
+    audience?: string | null;
+    brand_values?: string | null;
+    do_donts?: unknown;
+    keywords?: unknown;
+    competitors?: unknown;
+    custom_instructions?: string | null;
+    visual_guidelines?: unknown;
+    logo_url?: string | null;
+    brand_story?: string | null;
+    example_posts?: unknown;
+    topics_to_cover?: unknown;
+    topics_to_avoid?: unknown;
+    voice_examples?: unknown;
+    last_context_refresh_at?: string | null;
+    created_at?: string | null;
+    updated_at?: string | null;
+    source: 'canonical' | 'legacy';
+}
 export interface Post {
     id: number;
     content: string;
@@ -43,6 +78,86 @@ export interface Whoami {
     default_workspace: Workspace;
     workspaces: Workspace[];
 }
+export interface AccountAnalyticsSummary {
+    current_followers: number;
+    followers_change: number;
+    total_reach: number | null;
+    total_views: number | null;
+    total_accounts_engaged: number | null;
+    total_follows_gained: number;
+    total_follows_lost: number;
+    engagement_rate: number;
+    engagement_rate_by_followers: number;
+    total_website_clicks: number | null;
+    total_call_clicks: number | null;
+    total_direction_requests: number | null;
+    total_conversations: number | null;
+    total_bookings: number | null;
+}
+export interface AccountAnalyticsSnapshot {
+    date: string;
+    followers: number | null;
+    following: number | null;
+    media_count: number | null;
+    reach: number | null;
+    views: number | null;
+    profile_views: number | null;
+    accounts_engaged: number | null;
+    follows_gained: number | null;
+    follows_lost: number | null;
+    website_clicks: number | null;
+    call_clicks: number | null;
+    direction_requests: number | null;
+    conversations: number | null;
+    bookings: number | null;
+}
+export interface AccountAnalyticsResponse {
+    account: {
+        id: number;
+        platform: string;
+        username: string;
+    };
+    range: {
+        from: string;
+        to: string;
+    };
+    summary: AccountAnalyticsSummary;
+    snapshots: AccountAnalyticsSnapshot[];
+}
+export interface PostAnalyticsRow {
+    id: number | null;
+    platform_media_id: string;
+    platform: string;
+    posted_at: string | null;
+    likes: number;
+    comments: number;
+    impressions: number;
+    reach: number;
+    saved: number;
+    shares: number;
+    plays: number;
+    total_interactions: number;
+    media_type: string | null;
+    media_url: string | null;
+    permalink: string | null;
+    caption_snippet: string | null;
+    synced_at: string;
+}
+export interface PostAnalyticsResponse {
+    account: {
+        id: number;
+        platform: string;
+        username: string;
+    };
+    range: {
+        from: string;
+        to: string;
+    };
+    posts: PostAnalyticsRow[];
+    total: number;
+    limit: number;
+    offset: number;
+}
 export declare class PosterlyClient {
     private baseUrl;
     private apiKey;
@@ -52,9 +167,20 @@ export declare class PosterlyClient {
     listAccounts(params?: {
         workspace_id?: string;
     }): Promise<Account[]>;
+    listBrands(params?: {
+        workspace_id?: string;
+    }): Promise<Brand[]>;
+    getBrand(id: string): Promise<{
+        brand: Brand;
+    }>;
+    listBrandAccounts(id: string): Promise<Account[]>;
+    getBrandProfile(id: string): Promise<{
+        brand_profile: BrandProfile;
+    }>;
     listPosts(params?: {
         status?: string;
         platform?: string;
+        account_id?: string;
         limit?: number;
         offset?: number;
         workspace_id?: string;
@@ -130,6 +256,18 @@ export declare class PosterlyClient {
         count?: number;
         workspace_id?: string;
     }): Promise<Slot[]>;
+    getAccountAnalytics(params: {
+        account_id: number;
+        from?: string;
+        to?: string;
+    }): Promise<AccountAnalyticsResponse>;
+    getPostAnalytics(params: {
+        account_id: number;
+        from?: string;
+        to?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<PostAnalyticsResponse>;
     getSignedUploadUrl(filename: string, contentType: string, size: number): Promise<{
         upload_url: string;
         token: string;

package/dist/lib/api-client.js

@@ -41,12 +41,32 @@ export class PosterlyClient {
         const data = await this.request('GET', `/accounts${qs ? `?${qs}` : ''}`);
         return data.accounts;
     }
+    async listBrands(params) {
+        const searchParams = new URLSearchParams();
+        if (params?.workspace_id)
+            searchParams.set('workspace_id', params.workspace_id);
+        const qs = searchParams.toString();
+        const data = await this.request('GET', `/brands${qs ? `?${qs}` : ''}`);
+        return data.brands;
+    }
+    async getBrand(id) {
+        return this.request('GET', `/brands/${encodeURIComponent(id)}`);
+    }
+    async listBrandAccounts(id) {
+        const data = await this.request('GET', `/brands/${encodeURIComponent(id)}/accounts`);
+        return data.accounts;
+    }
+    async getBrandProfile(id) {
+        return this.request('GET', `/brands/${encodeURIComponent(id)}/profile`);
+    }
     async listPosts(params) {
         const searchParams = new URLSearchParams();
         if (params?.status)
             searchParams.set('status', params.status);
         if (params?.platform)
             searchParams.set('platform', params.platform);
+        if (params?.account_id)
+            searchParams.set('account_id', params.account_id);
         if (params?.limit)
             searchParams.set('limit', String(params.limit));
         if (params?.offset)
@@ -85,6 +105,28 @@ export class PosterlyClient {
         const data = await this.request('GET', `/slots/next${qs ? `?${qs}` : ''}`);
         return data.slots;
     }
+    async getAccountAnalytics(params) {
+        const searchParams = new URLSearchParams();
+        searchParams.set('account_id', String(params.account_id));
+        if (params.from)
+            searchParams.set('from', params.from);
+        if (params.to)
+            searchParams.set('to', params.to);
+        return this.request('GET', `/analytics/accounts?${searchParams.toString()}`);
+    }
+    async getPostAnalytics(params) {
+        const searchParams = new URLSearchParams();
+        searchParams.set('account_id', String(params.account_id));
+        if (params.from)
+            searchParams.set('from', params.from);
+        if (params.to)
+            searchParams.set('to', params.to);
+        if (params.limit)
+            searchParams.set('limit', String(params.limit));
+        if (params.offset)
+            searchParams.set('offset', String(params.offset));
+        return this.request('GET', `/analytics/posts?${searchParams.toString()}`);
+    }
     async getSignedUploadUrl(filename, contentType, size) {
         return this.request('POST', '/media/signed-upload', {
             filename,

package/dist/tools/get-account-analytics.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const getAccountAnalyticsTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        account_id: z.ZodNumber;
+        from: z.ZodOptional<z.ZodString>;
+        to: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        account_id: number;
+        from?: string | undefined;
+        to?: string | undefined;
+    }, {
+        account_id: number;
+        from?: string | undefined;
+        to?: string | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        account_id: number;
+        from?: string;
+        to?: string;
+    }): Promise<string>;
+};

package/dist/tools/get-account-analytics.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+export const getAccountAnalyticsTool = {
+    name: 'get_account_analytics',
+    description: 'Get daily analytics snapshots and a period summary for a connected social account. Supports Instagram, LinkedIn, and Google Business Profile. Returns follower growth, reach, views, engagement rate, and platform-specific metrics (e.g. website clicks, direction requests for GBP).',
+    inputSchema: z.object({
+        account_id: z
+            .number()
+            .describe('The social account ID (from list_accounts)'),
+        from: z
+            .string()
+            .optional()
+            .describe('Start date (ISO date, e.g. 2026-03-19). Defaults to 30 days ago.'),
+        to: z
+            .string()
+            .optional()
+            .describe('End date (ISO date). Defaults to today.'),
+    }),
+    async execute(client, input) {
+        const result = await client.getAccountAnalytics(input);
+        const { account, range, summary, snapshots } = result;
+        const lines = [
+            `Analytics for @${account.username} (${account.platform}, id ${account.id})`,
+            `Range: ${range.from} → ${range.to} (${snapshots.length} daily snapshots)`,
+            '',
+            'Summary:',
+            `• Followers: ${summary.current_followers.toLocaleString()} (${formatDelta(summary.followers_change)} in range)`,
+            `• Follows gained / lost: +${summary.total_follows_gained} / -${summary.total_follows_lost}`,
+        ];
+        if (summary.total_reach !== null)
+            lines.push(`• Total reach: ${summary.total_reach.toLocaleString()}`);
+        if (summary.total_views !== null)
+            lines.push(`• Total views: ${summary.total_views.toLocaleString()}`);
+        if (summary.total_accounts_engaged !== null) {
+            lines.push(`• Total accounts engaged: ${summary.total_accounts_engaged.toLocaleString()}`);
+        }
+        lines.push(`• Engagement rate (by reach): ${summary.engagement_rate}%`, `• Engagement rate (by followers): ${summary.engagement_rate_by_followers}%`);
+        if (account.platform === 'google_business') {
+            if (summary.total_website_clicks !== null) {
+                lines.push(`• Website clicks: ${summary.total_website_clicks.toLocaleString()}`);
+            }
+            if (summary.total_call_clicks !== null) {
+                lines.push(`• Call clicks: ${summary.total_call_clicks.toLocaleString()}`);
+            }
+            if (summary.total_direction_requests !== null) {
+                lines.push(`• Direction requests: ${summary.total_direction_requests.toLocaleString()}`);
+            }
+            if (summary.total_conversations !== null) {
+                lines.push(`• Conversations: ${summary.total_conversations.toLocaleString()}`);
+            }
+            if (summary.total_bookings !== null) {
+                lines.push(`• Bookings: ${summary.total_bookings.toLocaleString()}`);
+            }
+        }
+        return lines.join('\n');
+    },
+};
+function formatDelta(n) {
+    return n >= 0 ? `+${n.toLocaleString()}` : n.toLocaleString();
+}

package/dist/tools/get-brand-profile.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const getBrandProfileTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        brand_id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        brand_id: string;
+    }, {
+        brand_id: string;
+    }>;
+    execute(client: PosterlyClient, input: {
+        brand_id: string;
+    }): Promise<string>;
+};

package/dist/tools/get-brand-profile.js

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+export const getBrandProfileTool = {
+    name: 'get_brand_profile',
+    description: 'Get the extended brand profile for a brand/client. Returns voice/tone guidance, audience, keywords, dos and don’ts, visual notes, and other saved brand context.',
+    inputSchema: z.object({
+        brand_id: z.string().describe('The brand ID to inspect (from list_brands).'),
+    }),
+    async execute(client, input) {
+        const result = await client.getBrandProfile(input.brand_id);
+        const profile = result.brand_profile;
+        const lines = [
+            `Brand profile: ${profile.brand_name}`,
+            `• Source: ${profile.source}`,
+        ];
+        if (profile.workspace_client_id)
+            lines.push(`• Workspace client ID: ${profile.workspace_client_id}`);
+        if (profile.brand_group_id)
+            lines.push(`• Legacy brand group ID: ${profile.brand_group_id}`);
+        if (profile.tone_of_voice)
+            lines.push(`• Tone of voice: ${profile.tone_of_voice}`);
+        if (profile.audience)
+            lines.push(`• Audience: ${profile.audience}`);
+        if (profile.brand_values)
+            lines.push(`• Brand values: ${profile.brand_values}`);
+        if (profile.custom_instructions)
+            lines.push(`• Custom instructions: ${profile.custom_instructions}`);
+        if (profile.logo_url)
+            lines.push(`• Logo URL: ${profile.logo_url}`);
+        addStructuredLine(lines, 'Keywords', profile.keywords);
+        addStructuredLine(lines, 'Competitors', profile.competitors);
+        addStructuredLine(lines, 'Do / Don’ts', profile.do_donts);
+        addStructuredLine(lines, 'Visual guidelines', profile.visual_guidelines);
+        addStructuredLine(lines, 'Brand story', profile.brand_story);
+        addStructuredLine(lines, 'Example posts', profile.example_posts);
+        addStructuredLine(lines, 'Topics to cover', profile.topics_to_cover);
+        addStructuredLine(lines, 'Topics to avoid', profile.topics_to_avoid);
+        addStructuredLine(lines, 'Voice examples', profile.voice_examples);
+        if (profile.last_context_refresh_at) {
+            lines.push(`• Last refreshed: ${profile.last_context_refresh_at}`);
+        }
+        if (lines.length === 2) {
+            lines.push('• No extended brand profile fields have been saved yet.');
+        }
+        return lines.join('\n');
+    },
+};
+function addStructuredLine(lines, label, value) {
+    const formatted = formatStructuredValue(value);
+    if (formatted) {
+        lines.push(`• ${label}: ${formatted}`);
+    }
+}
+function formatStructuredValue(value) {
+    if (value == null)
+        return null;
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return null;
+        return value
+            .map((item) => formatStructuredValue(item) || JSON.stringify(item))
+            .filter(Boolean)
+            .join(' | ');
+    }
+    if (typeof value === 'object') {
+        const json = JSON.stringify(value);
+        return json === '{}' ? null : json;
+    }
+    return String(value);
+}

package/dist/tools/get-brand.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const getBrandTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        brand_id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        brand_id: string;
+    }, {
+        brand_id: string;
+    }>;
+    execute(client: PosterlyClient, input: {
+        brand_id: string;
+    }): Promise<string>;
+};