posterly-mcp-server 0.5.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';
@@ -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.6.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/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.6.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.6.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/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) {