posterly-mcp-server 0.5.0 → 0.7.0

package/README.md

@@ -0,0 +1,178 @@
+# 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.7.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
+- `30 requests/hour` per API key
+- user-created API keys per plan: Starter 1, Pro 2, Power User 3, Agency 4
+- works across all 11 supported platforms
+
+Each API call counts as one request, so you can still schedule multiple posts in a single request to maximize throughput.
+
+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';
@@ -16,7 +20,7 @@ import { getAccountAnalyticsTool } from './tools/get-account-analytics.js';
 import { getPostAnalyticsTool } from './tools/get-post-analytics.js';
 const server = new McpServer({
     name: 'posterly',
-    version: '0.5.0',
+    version: '0.7.0',
 });
 let client;
 try {
@@ -45,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);

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;
@@ -132,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;

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)

package/dist/tools/create-post.d.ts

@@ -7,42 +7,46 @@ export declare const createPostTool: {
         account_id: z.ZodOptional<z.ZodString>;
         username: z.ZodOptional<z.ZodString>;
         platform: z.ZodOptional<z.ZodString>;
-        caption: z.ZodString;
+        caption: z.ZodOptional<z.ZodString>;
         scheduled_at: z.ZodOptional<z.ZodString>;
         media_url: z.ZodOptional<z.ZodString>;
         media_urls: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         post_type: z.ZodOptional<z.ZodString>;
+        thread_posts: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         workspace_id: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        caption: string;
         workspace_id?: string | undefined;
         platform?: string | undefined;
         account_id?: string | undefined;
         username?: string | undefined;
+        caption?: string | undefined;
         scheduled_at?: string | undefined;
         media_url?: string | undefined;
         media_urls?: string[] | undefined;
         post_type?: string | undefined;
+        thread_posts?: string[] | undefined;
     }, {
-        caption: string;
         workspace_id?: string | undefined;
         platform?: string | undefined;
         account_id?: string | undefined;
         username?: string | undefined;
+        caption?: string | undefined;
         scheduled_at?: string | undefined;
         media_url?: string | undefined;
         media_urls?: string[] | undefined;
         post_type?: string | undefined;
+        thread_posts?: string[] | undefined;
     }>;
     execute(client: PosterlyClient, input: {
         account_id?: string;
         username?: string;
         platform?: string;
-        caption: string;
+        caption?: string;
         scheduled_at?: string;
         media_url?: string;
         media_urls?: string[];
         post_type?: string;
+        thread_posts?: string[];
         workspace_id?: string;
     }): Promise<string>;
 };

package/dist/tools/create-post.js

@@ -7,7 +7,8 @@ export const createPostTool = {
         '2. Show the user a preview containing ALL of: account(s) and platform(s), final caption text, scheduled time (in the user\'s timezone), media attached (if any), and workspace name.\n' +
         '3. Get explicit confirmation from the user (e.g. "post it", "yes schedule that", "looks good") BEFORE calling this tool. Do NOT infer consent from earlier instructions like "post about X every Monday" — confirm each individual post or the entire batch.\n' +
         '4. If scheduling multiple posts in one turn, list every post first and confirm the batch as a whole before calling create_post repeatedly.\n\n' +
-        'Provide either account_id OR username+platform to identify the account. If scheduled_at is omitted, the post publishes immediately. If workspace_id is omitted, the server resolves one from the social account, falling back to the caller\'s default (personal) workspace — pass workspace_id explicitly if the user has more than one workspace.',
+        'Provide either account_id OR username+platform to identify the account. If scheduled_at is omitted, the post publishes immediately. If workspace_id is omitted, the server resolves one from the social account, falling back to the caller\'s default (personal) workspace — pass workspace_id explicitly if the user has more than one workspace.\n\n' +
+        'THREADS: Pass `thread_posts` (an array of 2+ strings) to schedule a multi-post thread on X (Twitter) or Threads (Meta). The first entry is the lead post; the rest are published as replies in the same chain. X entries are capped at 280 characters each (4000 for verified, 25000 for organization accounts); Threads entries are capped at 500 characters each. When `thread_posts` is set, `caption` is ignored.',
     inputSchema: z.object({
         account_id: z.string().optional().describe('Social account ID (from list_accounts)'),
         username: z.string().optional().describe('Account username (alternative to account_id)'),
@@ -15,12 +16,12 @@ export const createPostTool = {
             .string()
             .optional()
             .describe('Platform name (required with username): instagram, twitter, linkedin, facebook, tiktok, threads, youtube, pinterest, google_business'),
-        caption: z.string().describe('The post caption/text content'),
+        caption: z.string().optional().describe('The post caption/text content. Ignored when `thread_posts` is provided.'),
         scheduled_at: z
             .string()
             .optional()
             .describe('ISO 8601 datetime for scheduling (e.g. 2026-03-05T09:00:00Z). Omit for immediate publish.'),
-        media_url: z.string().optional().describe('URL of media to attach (image or video)'),
+        media_url: z.string().optional().describe('URL of media to attach (image or video). For threads, attaches to the lead post only.'),
         media_urls: z
             .array(z.string())
             .optional()
@@ -28,14 +29,49 @@ export const createPostTool = {
         post_type: z
             .string()
             .optional()
-            .describe('Post type: text, image, video, carousel, reel, story'),
+            .describe('Post type: text, image, video, carousel, reel, story. Auto-set to x_thread/threads_thread when `thread_posts` is provided.'),
+        thread_posts: z
+            .array(z.string())
+            .optional()
+            .describe('For X or Threads only: array of 2+ strings, one per post in the thread. The first entry leads, the rest reply in order. When set, the platform must be twitter or threads.'),
         workspace_id: z
             .string()
             .optional()
             .describe('Workspace ID to assign the post to (from whoami). If omitted, uses the account\'s workspace or the caller\'s default workspace.'),
     }),
     async execute(client, input) {
-        const result = await client.createPost(input);
+        const { thread_posts, caption, post_type, ...rest } = input;
+        let payload;
+        if (thread_posts && thread_posts.length > 0) {
+            if (thread_posts.length < 2) {
+                throw new Error('thread_posts must contain at least 2 entries');
+            }
+            const platformHint = (input.platform || '').toLowerCase();
+            const isTwitter = platformHint === 'twitter' || platformHint === 'x';
+            const isThreads = platformHint === 'threads';
+            if (!isTwitter && !isThreads && !input.account_id) {
+                throw new Error('thread_posts requires `platform` to be "twitter" or "threads", or pass `account_id` for an X/Threads account.');
+            }
+            const arrayKey = isThreads ? 'threads_thread_posts' : 'x_thread_tweets';
+            const totalKey = isThreads ? 'threads_thread_total' : 'x_thread_total';
+            payload = {
+                ...rest,
+                platform: isTwitter ? 'twitter' : isThreads ? 'threads' : input.platform,
+                caption: thread_posts[0],
+                post_type: isThreads ? 'threads_thread' : 'x_thread',
+                metadata: {
+                    [arrayKey]: thread_posts,
+                    [totalKey]: thread_posts.length,
+                },
+            };
+        }
+        else {
+            if (!caption) {
+                throw new Error('caption is required (or pass `thread_posts` for an X/Threads thread)');
+            }
+            payload = { ...rest, caption, post_type };
+        }
+        const result = await client.createPost(payload);
         const p = result.post;
         const ws = result.workspace;
         const when = p.scheduled_at
@@ -49,6 +85,9 @@ export const createPostTool = {
             `• Status: ${p.status}`,
             `• Scheduled: ${when}`,
         ];
+        if (thread_posts) {
+            lines.push(`• Thread: ${thread_posts.length} posts`);
+        }
         if (ws) {
             lines.push(`• Workspace: ${ws.name} (${ws.id}) — resolved from ${ws.resolved_from}`);
         }

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>;
+};

package/dist/tools/get-brand.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+export const getBrandTool = {
+    name: 'get_brand',
+    description: 'Get one brand/client by ID. Returns its workspace, source, linked legacy brand group if present, and the number of social accounts assigned to it.',
+    inputSchema: z.object({
+        brand_id: z.string().describe('The brand ID to look up (from list_brands).'),
+    }),
+    async execute(client, input) {
+        const result = await client.getBrand(input.brand_id);
+        const brand = result.brand;
+        const lines = [
+            `Brand: ${brand.name}`,
+            `• ID: ${brand.id}`,
+            `• Source: ${brand.source}`,
+            `• Workspace: ${brand.workspace_id || 'N/A'}`,
+            `• Accounts assigned: ${brand.account_count ?? 0}`,
+        ];
+        if (brand.workspace_client_id)
+            lines.push(`• Workspace client ID: ${brand.workspace_client_id}`);
+        if (brand.legacy_brand_group_id)
+            lines.push(`• Legacy brand group ID: ${brand.legacy_brand_group_id}`);
+        if (brand.created_at)
+            lines.push(`• Created: ${brand.created_at}`);
+        if (brand.updated_at)
+            lines.push(`• Updated: ${brand.updated_at}`);
+        return lines.join('\n');
+    },
+};

package/dist/tools/list-brand-accounts.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const listBrandAccountsTool: {
+    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/list-brand-accounts.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export const listBrandAccountsTool = {
+    name: 'list_brand_accounts',
+    description: 'List the connected social accounts assigned to a brand/client. Use this when a user refers to a brand name rather than a raw account handle.',
+    inputSchema: z.object({
+        brand_id: z.string().describe('The brand ID to inspect (from list_brands).'),
+    }),
+    async execute(client, input) {
+        const accounts = await client.listBrandAccounts(input.brand_id);
+        if (accounts.length === 0) {
+            return 'No social accounts are currently assigned to this brand.';
+        }
+        const lines = accounts.map((account) => `• ${account.platform} — @${account.username} (ID: ${account.id}${account.workspace_id ? `, ws: ${account.workspace_id}` : ''})`);
+        return `Brand accounts (${accounts.length}):\n${lines.join('\n')}`;
+    },
+};

package/dist/tools/list-brands.d.ts

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

package/dist/tools/list-brands.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+export const listBrandsTool = {
+    name: 'list_brands',
+    description: 'List brands/clients the caller can access. Returns each brand ID, name, workspace ID, source, and how many social accounts are currently assigned to it.',
+    inputSchema: z.object({
+        workspace_id: z
+            .string()
+            .optional()
+            .describe('Filter to brands in a specific workspace (get IDs via whoami).'),
+    }),
+    async execute(client, input) {
+        const brands = await client.listBrands({ workspace_id: input.workspace_id });
+        if (brands.length === 0) {
+            return input.workspace_id
+                ? 'No brands found in this workspace.'
+                : 'No brands found. Create brands in the posterly dashboard first.';
+        }
+        const lines = brands.map((brand) => {
+            const suffix = [
+                `ID: ${brand.id}`,
+                brand.workspace_id ? `ws: ${brand.workspace_id}` : null,
+                `accounts: ${brand.account_count}`,
+                brand.source,
+            ].filter(Boolean).join(', ');
+            return `• ${brand.name} (${suffix})`;
+        });
+        return `Brands (${brands.length}):\n${lines.join('\n')}`;
+    },
+};

package/dist/tools/list-posts.d.ts

@@ -6,22 +6,26 @@ export declare const listPostsTool: {
     inputSchema: z.ZodObject<{
         status: z.ZodOptional<z.ZodString>;
         platform: z.ZodOptional<z.ZodString>;
+        account_id: z.ZodOptional<z.ZodString>;
         limit: z.ZodOptional<z.ZodNumber>;
         workspace_id: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         workspace_id?: string | undefined;
         status?: string | undefined;
         platform?: string | undefined;
+        account_id?: string | undefined;
         limit?: number | undefined;
     }, {
         workspace_id?: string | undefined;
         status?: string | undefined;
         platform?: string | undefined;
+        account_id?: string | undefined;
         limit?: number | undefined;
     }>;
     execute(client: PosterlyClient, input: {
         status?: string;
         platform?: string;
+        account_id?: string;
         limit?: number;
         workspace_id?: string;
     }): Promise<string>;

package/dist/tools/list-posts.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 export const listPostsTool = {
     name: 'list_posts',
-    description: 'List upcoming or recent posts. Filter by status (scheduled, published, failed, draft), platform, or workspace_id. If workspace_id is omitted, posts across every workspace the caller is a member of are returned.',
+    description: 'List upcoming or recent posts. Filter by status (scheduled, published, failed, draft), platform, account_id, or workspace_id. If workspace_id is omitted, posts across every workspace the caller is a member of are returned.',
     inputSchema: z.object({
         status: z
             .string()
@@ -11,12 +11,16 @@ export const listPostsTool = {
             .string()
             .optional()
             .describe('Filter by platform: instagram, twitter, linkedin, etc.'),
+        account_id: z
+            .string()
+            .optional()
+            .describe('Filter to a specific social account ID (from list_accounts).'),
         limit: z
             .number()
             .min(1)
-            .max(50)
+            .max(100)
             .optional()
-            .describe('Number of posts to return (default 10, max 50)'),
+            .describe('Number of posts to return (default 20, max 100)'),
         workspace_id: z
             .string()
             .optional()
@@ -25,7 +29,7 @@ export const listPostsTool = {
     async execute(client, input) {
         const { posts, total } = await client.listPosts({
             ...input,
-            limit: input.limit || 10,
+            limit: input.limit || 20,
         });
         if (posts.length === 0) {
             return 'No posts found matching your criteria.';

package/package.json

@@ -1,8 +1,27 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "MCP server for posterly — schedule social media posts from Claude Desktop",
   "license": "MIT",
+  "homepage": "https://www.poster.ly/mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/awpthorp/posterly.git",
+    "directory": "mcp-server"
+  },
+  "bugs": {
+    "url": "https://github.com/awpthorp/posterly/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "posterly",
+    "social-media",
+    "scheduling",
+    "claude",
+    "cursor",
+    "chatgpt"
+  ],
   "type": "module",
   "bin": {
     "posterly-mcp": "./dist/index.js"

package/src/index.ts

@@ -4,6 +4,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';
@@ -18,7 +22,7 @@ import { getPostAnalyticsTool } from './tools/get-post-analytics.js';
 
 const server = new McpServer({
   name: 'posterly',
-  version: '0.5.0',
+  version: '0.7.0',
 });
 
 let client: PosterlyClient;
@@ -59,6 +63,62 @@ server.tool(
   }
 );
 
+server.tool(
+  listBrandsTool.name,
+  listBrandsTool.description,
+  listBrandsTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await listBrandsTool.execute(client, input as any);
+      return { content: [{ type: 'text' as const, text }] };
+    } catch (err: any) {
+      return { content: [{ type: 'text' as const, 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 as any);
+      return { content: [{ type: 'text' as const, text }] };
+    } catch (err: any) {
+      return { content: [{ type: 'text' as const, 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 as any);
+      return { content: [{ type: 'text' as const, text }] };
+    } catch (err: any) {
+      return { content: [{ type: 'text' as const, 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 as any);
+      return { content: [{ type: 'text' as const, text }] };
+    } catch (err: any) {
+      return { content: [{ type: 'text' as const, text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
 server.tool(
   createPostTool.name,
   createPostTool.description,

package/src/lib/api-client.ts

@@ -10,6 +10,43 @@ export interface Account {
   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;
@@ -170,9 +207,31 @@ export class PosterlyClient {
     return data.accounts;
   }
 
+  async listBrands(params?: { workspace_id?: string }): Promise<Brand[]> {
+    const searchParams = new URLSearchParams();
+    if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);
+    const qs = searchParams.toString();
+    const data = await this.request<{ brands: Brand[] }>('GET', `/brands${qs ? `?${qs}` : ''}`);
+    return data.brands;
+  }
+
+  async getBrand(id: string): Promise<{ brand: Brand }> {
+    return this.request('GET', `/brands/${encodeURIComponent(id)}`);
+  }
+
+  async listBrandAccounts(id: string): Promise<Account[]> {
+    const data = await this.request<{ accounts: Account[] }>('GET', `/brands/${encodeURIComponent(id)}/accounts`);
+    return data.accounts;
+  }
+
+  async getBrandProfile(id: string): Promise<{ brand_profile: BrandProfile }> {
+    return this.request('GET', `/brands/${encodeURIComponent(id)}/profile`);
+  }
+
   async listPosts(params?: {
     status?: string;
     platform?: string;
+    account_id?: string;
     limit?: number;
     offset?: number;
     workspace_id?: string;
@@ -180,6 +239,7 @@ export class PosterlyClient {
     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) searchParams.set('offset', String(params.offset));
     if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);

package/src/tools/create-post.ts

@@ -10,7 +10,8 @@ export const createPostTool = {
     '2. Show the user a preview containing ALL of: account(s) and platform(s), final caption text, scheduled time (in the user\'s timezone), media attached (if any), and workspace name.\n' +
     '3. Get explicit confirmation from the user (e.g. "post it", "yes schedule that", "looks good") BEFORE calling this tool. Do NOT infer consent from earlier instructions like "post about X every Monday" — confirm each individual post or the entire batch.\n' +
     '4. If scheduling multiple posts in one turn, list every post first and confirm the batch as a whole before calling create_post repeatedly.\n\n' +
-    'Provide either account_id OR username+platform to identify the account. If scheduled_at is omitted, the post publishes immediately. If workspace_id is omitted, the server resolves one from the social account, falling back to the caller\'s default (personal) workspace — pass workspace_id explicitly if the user has more than one workspace.',
+    'Provide either account_id OR username+platform to identify the account. If scheduled_at is omitted, the post publishes immediately. If workspace_id is omitted, the server resolves one from the social account, falling back to the caller\'s default (personal) workspace — pass workspace_id explicitly if the user has more than one workspace.\n\n' +
+    'THREADS: Pass `thread_posts` (an array of 2+ strings) to schedule a multi-post thread on X (Twitter) or Threads (Meta). The first entry is the lead post; the rest are published as replies in the same chain. X entries are capped at 280 characters each (4000 for verified, 25000 for organization accounts); Threads entries are capped at 500 characters each. When `thread_posts` is set, `caption` is ignored.',
   inputSchema: z.object({
     account_id: z.string().optional().describe('Social account ID (from list_accounts)'),
     username: z.string().optional().describe('Account username (alternative to account_id)'),
@@ -18,12 +19,12 @@ export const createPostTool = {
       .string()
       .optional()
       .describe('Platform name (required with username): instagram, twitter, linkedin, facebook, tiktok, threads, youtube, pinterest, google_business'),
-    caption: z.string().describe('The post caption/text content'),
+    caption: z.string().optional().describe('The post caption/text content. Ignored when `thread_posts` is provided.'),
     scheduled_at: z
       .string()
       .optional()
       .describe('ISO 8601 datetime for scheduling (e.g. 2026-03-05T09:00:00Z). Omit for immediate publish.'),
-    media_url: z.string().optional().describe('URL of media to attach (image or video)'),
+    media_url: z.string().optional().describe('URL of media to attach (image or video). For threads, attaches to the lead post only.'),
     media_urls: z
       .array(z.string())
       .optional()
@@ -31,7 +32,11 @@ export const createPostTool = {
     post_type: z
       .string()
       .optional()
-      .describe('Post type: text, image, video, carousel, reel, story'),
+      .describe('Post type: text, image, video, carousel, reel, story. Auto-set to x_thread/threads_thread when `thread_posts` is provided.'),
+    thread_posts: z
+      .array(z.string())
+      .optional()
+      .describe('For X or Threads only: array of 2+ strings, one per post in the thread. The first entry leads, the rest reply in order. When set, the platform must be twitter or threads.'),
     workspace_id: z
       .string()
       .optional()
@@ -44,15 +49,50 @@ export const createPostTool = {
       account_id?: string;
       username?: string;
       platform?: string;
-      caption: string;
+      caption?: string;
       scheduled_at?: string;
       media_url?: string;
       media_urls?: string[];
       post_type?: string;
+      thread_posts?: string[];
       workspace_id?: string;
     }
   ) {
-    const result = await client.createPost(input);
+    const { thread_posts, caption, post_type, ...rest } = input;
+    let payload: Parameters<typeof client.createPost>[0];
+
+    if (thread_posts && thread_posts.length > 0) {
+      if (thread_posts.length < 2) {
+        throw new Error('thread_posts must contain at least 2 entries');
+      }
+      const platformHint = (input.platform || '').toLowerCase();
+      const isTwitter = platformHint === 'twitter' || platformHint === 'x';
+      const isThreads = platformHint === 'threads';
+      if (!isTwitter && !isThreads && !input.account_id) {
+        throw new Error(
+          'thread_posts requires `platform` to be "twitter" or "threads", or pass `account_id` for an X/Threads account.',
+        );
+      }
+      const arrayKey = isThreads ? 'threads_thread_posts' : 'x_thread_tweets';
+      const totalKey = isThreads ? 'threads_thread_total' : 'x_thread_total';
+      payload = {
+        ...rest,
+        platform: isTwitter ? 'twitter' : isThreads ? 'threads' : input.platform,
+        caption: thread_posts[0],
+        post_type: isThreads ? 'threads_thread' : 'x_thread',
+        metadata: {
+          [arrayKey]: thread_posts,
+          [totalKey]: thread_posts.length,
+        },
+      };
+    } else {
+      if (!caption) {
+        throw new Error('caption is required (or pass `thread_posts` for an X/Threads thread)');
+      }
+      payload = { ...rest, caption, post_type };
+    }
+
+    const result = await client.createPost(payload);
     const p = result.post as Record<string, any>;
     const ws = result.workspace;
 
@@ -68,6 +108,9 @@ export const createPostTool = {
       `• Status: ${p.status}`,
       `• Scheduled: ${when}`,
     ];
+    if (thread_posts) {
+      lines.push(`• Thread: ${thread_posts.length} posts`);
+    }
     if (ws) {
       lines.push(`• Workspace: ${ws.name} (${ws.id}) — resolved from ${ws.resolved_from}`);
     }

package/src/tools/get-brand-profile.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+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: PosterlyClient,
+    input: { brand_id: string },
+  ) {
+    const result = await client.getBrandProfile(input.brand_id);
+    const profile = result.brand_profile as Record<string, any>;
+
+    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: string[], label: string, value: unknown) {
+  const formatted = formatStructuredValue(value);
+  if (formatted) {
+    lines.push(`• ${label}: ${formatted}`);
+  }
+}
+
+function formatStructuredValue(value: unknown): string | null {
+  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/src/tools/get-brand.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const getBrandTool = {
+  name: 'get_brand',
+  description:
+    'Get one brand/client by ID. Returns its workspace, source, linked legacy brand group if present, and the number of social accounts assigned to it.',
+  inputSchema: z.object({
+    brand_id: z.string().describe('The brand ID to look up (from list_brands).'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: { brand_id: string },
+  ) {
+    const result = await client.getBrand(input.brand_id);
+    const brand = result.brand as Record<string, any>;
+
+    const lines = [
+      `Brand: ${brand.name}`,
+      `• ID: ${brand.id}`,
+      `• Source: ${brand.source}`,
+      `• Workspace: ${brand.workspace_id || 'N/A'}`,
+      `• Accounts assigned: ${brand.account_count ?? 0}`,
+    ];
+
+    if (brand.workspace_client_id) lines.push(`• Workspace client ID: ${brand.workspace_client_id}`);
+    if (brand.legacy_brand_group_id) lines.push(`• Legacy brand group ID: ${brand.legacy_brand_group_id}`);
+    if (brand.created_at) lines.push(`• Created: ${brand.created_at}`);
+    if (brand.updated_at) lines.push(`• Updated: ${brand.updated_at}`);
+
+    return lines.join('\n');
+  },
+};

package/src/tools/list-brand-accounts.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const listBrandAccountsTool = {
+  name: 'list_brand_accounts',
+  description:
+    'List the connected social accounts assigned to a brand/client. Use this when a user refers to a brand name rather than a raw account handle.',
+  inputSchema: z.object({
+    brand_id: z.string().describe('The brand ID to inspect (from list_brands).'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: { brand_id: string },
+  ) {
+    const accounts = await client.listBrandAccounts(input.brand_id);
+
+    if (accounts.length === 0) {
+      return 'No social accounts are currently assigned to this brand.';
+    }
+
+    const lines = accounts.map(
+      (account) => `• ${account.platform} — @${account.username} (ID: ${account.id}${account.workspace_id ? `, ws: ${account.workspace_id}` : ''})`
+    );
+
+    return `Brand accounts (${accounts.length}):\n${lines.join('\n')}`;
+  },
+};

package/src/tools/list-brands.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const listBrandsTool = {
+  name: 'list_brands',
+  description:
+    'List brands/clients the caller can access. Returns each brand ID, name, workspace ID, source, and how many social accounts are currently assigned to it.',
+  inputSchema: z.object({
+    workspace_id: z
+      .string()
+      .optional()
+      .describe('Filter to brands in a specific workspace (get IDs via whoami).'),
+  }),
+
+  async execute(client: PosterlyClient, input: { workspace_id?: string }) {
+    const brands = await client.listBrands({ workspace_id: input.workspace_id });
+
+    if (brands.length === 0) {
+      return input.workspace_id
+        ? 'No brands found in this workspace.'
+        : 'No brands found. Create brands in the posterly dashboard first.';
+    }
+
+    const lines = brands.map((brand) => {
+      const suffix = [
+        `ID: ${brand.id}`,
+        brand.workspace_id ? `ws: ${brand.workspace_id}` : null,
+        `accounts: ${brand.account_count}`,
+        brand.source,
+      ].filter(Boolean).join(', ');
+      return `• ${brand.name} (${suffix})`;
+    });
+
+    return `Brands (${brands.length}):\n${lines.join('\n')}`;
+  },
+};

package/src/tools/list-posts.ts

@@ -4,7 +4,7 @@ import type { PosterlyClient } from '../lib/api-client.js';
 export const listPostsTool = {
   name: 'list_posts',
   description:
-    'List upcoming or recent posts. Filter by status (scheduled, published, failed, draft), platform, or workspace_id. If workspace_id is omitted, posts across every workspace the caller is a member of are returned.',
+    'List upcoming or recent posts. Filter by status (scheduled, published, failed, draft), platform, account_id, or workspace_id. If workspace_id is omitted, posts across every workspace the caller is a member of are returned.',
   inputSchema: z.object({
     status: z
       .string()
@@ -14,12 +14,16 @@ export const listPostsTool = {
       .string()
       .optional()
       .describe('Filter by platform: instagram, twitter, linkedin, etc.'),
+    account_id: z
+      .string()
+      .optional()
+      .describe('Filter to a specific social account ID (from list_accounts).'),
     limit: z
       .number()
       .min(1)
-      .max(50)
+      .max(100)
       .optional()
-      .describe('Number of posts to return (default 10, max 50)'),
+      .describe('Number of posts to return (default 20, max 100)'),
     workspace_id: z
       .string()
       .optional()
@@ -28,11 +32,17 @@ export const listPostsTool = {
 
   async execute(
     client: PosterlyClient,
-    input: { status?: string; platform?: string; limit?: number; workspace_id?: string }
+    input: {
+      status?: string;
+      platform?: string;
+      account_id?: string;
+      limit?: number;
+      workspace_id?: string;
+    }
   ) {
     const { posts, total } = await client.listPosts({
       ...input,
-      limit: input.limit || 10,
+      limit: input.limit || 20,
     });
 
     if (posts.length === 0) {