io.github.bitsandtea/postking-mcp

Update the title or instructions of a landing page. For AI-powered edits, use vibe_edit_landing_page.

Edit a single carousel card on a post by its 1-based index. Provide title and/or body to update. Set rerender=true to regenerate the visual asset.

Update the instructions or metadata of a side page. For section-level edits, use set_side_page_section.

Edit an existing content theme's title or content instructions.

Enable the weekly content schedule without changing its configuration. The schedule must already be created with set_weekly_schedule.

Generate a full AI blog article. Requires a publicationId (from list_blogs or create_publication). Pass a voiceProfileId to write in a specific person's style (IDs from list_voices). Returns an articleId + operationId; generation is async — poll get_blog_status until completed, then get_blog_article. Use update_blog_article to edit, or publish_blog_article to push to external platforms. To make it live on your PostKing blog, call update_blog_article with status: 'published'.

Generate and schedule multiple posts across a date range in the background.

Generate a secure browser link to connect a social media account. Share this URL with the user to complete OAuth.

Create and AI-generate a new landing page for the brand. Step 1: Creates the LP record with the given slug. Step 2: Kicks off async AI content generation immediately. Returns { slug, operationId, pollUrl } — poll with get_job(operationId) until state is 'completed' (or 'failed'/'partially_failed'/'cancelled' on error).

Generate AI content for a platform. Polls until complete. Deducts 10 credits per variation. To control what the post is about, pass `theme` with a free-text brief (any topic/angle/facts/tone). If you omit `theme`, the topic is RANDOM — so always pass it when the user wants specific content. When variations > 1, ALL variations are returned under a SINGLE postId in the `variations` array — it does NOT create one post per variation. `content` is variation 1 (the primary, already saved on the post). Never call generate_post again to 'get the other variations' — they're all in the response. `originalContent` (if seen elsewhere) is the pre-voice-rewrite draft, not a separate variation. After generating, use create_post to save a chosen variation, then approve_post to schedule it. To repurpose: call repurpose_content first, then create_post with the result, then approve_post. Generation can take 1-5 minutes (longer with multiple variations or voice rewrite); this tool waits for completion. If it ever returns status 'still_generating', DO NOT write the post yourself — poll get_post with the returned postId until operationStatus is 'completed', then use that content. After generation, brand visual options (quote/card templates, brand images, stock photos) are prepared but NOT attached — share viewInBrowser for the visual picker, or call pick_post_visual to attach one. Do not attach a visual unless the user chooses it. The response includes editInVisualEditor: a direct URL to edit the post in the visual editor.

Generate a carousel PDF for a LinkedIn (or other) post from the post's cards. Returns an asset ID and download URL for the PDF. Requires cards to be set first via set_post_cards or edit_post_card.

Fetch available visual options for a post — card templates, library matches, stock photos. Returns a bestPick recommendation plus categorized options per platform. Use pick_post_visual to apply one of the returned options. Returns slim option list with pickArgs by default (medium). Use detail='short' for counts only, 'full' for raw catalog. Includes editInVisualEditor: a direct URL to edit the post in the visual editor (when active brand is set).

AI-generates a side page under a parent landing page. Async — kicks off the side-page generator and returns `{ success, operationId, operationRowId, pollUrl, sidePageId }`. This is the GENERATOR (POST /side-pages/generate) — NOT a row creator. Comparison-type briefs may run synchronously and return `sidePageId` directly with no operationId. Two body modes: • freeform: pass `key` + `prompt` (+ optional `keywords`, `selectedSections`, `voiceProfileId`, `sidePageType`). • brief: pass `key` + `brief` (structured outline) + optional `briefId` and `roadmapItemId`. Poll `get_job` until `state` is `completed` (or `failed`/`partially_failed`/`cancelled` on error).

Generate or rewrite general-purpose, email-style/formal text — follow-up emails, cover letters, outreach messages, formal notes, etc. Polls until complete. This is NOT for social media posts — use generate_post for those. This is also NOT for a simple voice-only rewrite of existing text with no other options — for that, use rewrite_with_voice or rewrite_text instead. Reach for generate_text when you need mode selection (generate vs rewrite), a stated purpose, a target length, or when there's no source text at all (mode='generate'). mode='generate' writes new text from a `prompt` (what to write, e.g. 'a follow-up email after a sales call, polite but direct'). mode='rewrite' rewrites existing `sourceText` into a new form/tone. `purpose` is optional free text describing the goal, e.g. 'win-back email' or 'job application cover letter'. `length` can be short | medium | long, or a specific target word count (20-5000). Supports detail param: short=status+wordCount only, medium=truncated content (500 chars)+wordCount (default), full=raw result including content, aiDetectionScore, burstinessScore, promptLogId, wordCount.

Generate new content themes using AI. Polls until complete. Deducts credits.

Fetch the brand's audience intelligence / ICP (ideal customer profile). short = compact summary (name + primaryRoles + top painPoints + persona.role); medium adds positioning + fuller demographics; full = the raw payload (audienceData + positioning + persona + contentModulation). `persona` is the ghostwriter persona ({ role, styleNotes, ... }) and may be null. If the brand has no audience data yet, run website/audience analysis (onboarding) first.

Fetch a blog article by ID. detail='short' returns id/title/slug/status; detail='medium' adds excerpt+wordCount+previewUrl+editUrl; detail='full' (default) returns the COMPLETE content plus previewUrl (GUI preview link) and editUrl (dashboard editor link). Pass maxContentChars only if you need to bound the body size; omit it to get the whole article.

Poll the async generation status of a blog article. Use the articleId returned by generate_blog_post. Status: pending | running | completed | failed.

Get a brand's profile. Returns core identity fields plus slim summaries: themes as [{id,title}], voiceProfiles as [{id,name,isActive,optimizedMedium}], blogAuthors as [{id,firstName,lastName}], and postCount/memberCount as numbers. Use list_themes, list_voices, list_blog_authors, list_posts, or get_brand_members for full detail on each.

Read which publishing platforms (mediums) a brand posts to. Read-only counterpart to set_brand_mediums. NOTE: Reddit is NOT a medium — Reddit is a separate repurpose module; use the reddit_* tools or dashboard_link section 'reddit'.

List all active members of a brand with their role and user info (id, name, email).

View upcoming scheduled posts sorted by date. Returns id+status+scheduledAt by default; use detail='medium' or 'full' for more fields. For a single post use get_post.

Check your current PostKing credit balance and free-tier status.

To check whether ONE specific operation you started is finished, pending, or failed, call this with its operationId (the `pollUrl` param accepts a bare operationId + brandId). Do NOT use list_operations to check a specific op. Poll the status of any background Operation by its operationId or pollUrl. Returns the Operation row: { id, kind, state (pending|running|completed|partially_failed|failed|cancelled), brandId, scopeType, scopeId, progress, result, errors, startedAt, finishedAt, createdAt, updatedAt }. Call repeatedly until state is 'completed' or 'failed' (or 'cancelled'). When completed, the payload you want is in `result`; on failure, see `errors`. Pass wait:true to block until the job is done (polls every 3s, up to ~2 min) — preferred over calling repeatedly. Most generate_* and vibe_edit_* tools (including seo_generate_clusters and seo_generate_keywords) return an operationId — use this to poll them. Supports detail param: short=id+kind+state+progress, medium=adds timestamps+resultRef (key IDs from result, no full payload), full=raw including complete result JSONB.

STEP 3 of brand onboarding. Polls background analysis + theme generation. detail='short' returns status only; detail='medium' (default) adds audienceSummary+themeCount; detail='full' returns raw data. Poll every ~15s. When done, surface the audience review + themes to the user.

View the full content and status of a single post. Use detail='short'|'medium'|'full' to control verbosity (default full). Multi-variation posts expose a `variations` array (all variations live on one postId). Output shows the final voice-rewritten content by default; pass includeOriginal=true to also see the pre-rewrite draft. Includes editInVisualEditor: a direct URL to edit the post in the visual editor.

View the SEO / GEO content roadmap — suggested blog topics, keywords, and completion status. detail='short' returns stats only; detail='medium' adds slim item list (id+title+status+keyword); detail='full' (default) returns raw response.

Read a brand's per-platform social media content rules (the same rules editable in dashboard Settings → Social media rules). Covers content/structure/engagement/visual-strategy guidance plus secrets, guidelines, content types, things to avoid, and core principles. Call this BEFORE set_social_media_rules so you only change the fields you intend to.

Poll vibe (AI) edit status. detail='full' (default) includes the result payload; 'short'/'medium' return just state+progress.

Retrieve the current weekly content schedule for the active brand. Returns enabled status, lead time, timezone, and per-day platform configs. If no schedule is configured yet, returns suggested defaults. Includes a viewInBrowser link to open the calendar page in the app.

Check PostKing API health and local auth state. No authentication required — safe to call first thing in a session to see whether you're logged in and what to do next.

Apply LLM rewrite and BERT replacements to reduce AI detection signals in text.

Import an asset into the brand library from a public URL. The server fetches and stores the file. Set assetType (e.g. 'google-image') when importing a result surfaced by search_web_images — it is recorded as a tag on the asset to preserve provenance.

Batch-import up to 50 assets by providing an array of public URLs. All are added to the brand library. Supports detail param for the returned asset list.

Import articles from an external blog, RSS feed, or Blogger URL into a PostKing publication as drafts. Returns id+title+slug by default (short); use detail='medium' for wordCount. Inspect individual articles with get_blog_article.

Async. Create a new knowledge-base item for the brand. Returns { operationId, status } — poll get_job until state=completed. If description or tags are omitted, PostKing auto-generates them from the content. For contentType='json', content must be valid JSON — this tool validates client-side before calling the API. Typically takes ~15–30 s.

Soft-delete a knowledge-base item. The item is deactivated (isActive=false) and no longer appears in knowledge_list. This action is not reversible via the API.

Fetch a single knowledge-base item by ID. short {id,name,contentType}; medium adds tags+summary+timestamps; full = raw (includes full content). Use detail='full' to retrieve the complete content body.

List the brand's knowledge-base items. short {id,name,contentType}; medium adds tags+summary+timestamps; full = raw. Filter by tag, active status, or global scope.

Update a knowledge-base item. Minor edits (name, tags, description) return the updated item synchronously. When content changes significantly, PostKing queues an AI description regeneration and returns { operationId, status } — poll get_job until state=completed. For contentType='json', content must be valid JSON — this tool validates client-side before calling the API. Typically takes ~15–30 s.

List all API keys on the account. Shows prefix, scope, and revocation status. Does NOT show raw tokens. Lists default short; pass detail=medium/full for more fields.

List all unique tags used across the brand's asset library.

List assets in the brand's visual library. Filter by type (IMAGE|DOCUMENT|VIDEO|LINK|LOTTIE), tags, or search text. Supports detail param: short=id+type+name, medium=key fields, full=raw.

List all blog authors for the active brand. Returns id+name by default (short); use detail='medium' for email/social links. Author IDs can be passed to generate_blog_post or update_blog_article.

List all categories for a blog publication. Returns id+name+slug by default (short); use detail='medium' for description+articleCount.

LIST tool. Even detail='full' OMITS article bodies (kept bounded) — to read an article's content, call get_blog_article. The number of rows is controlled by `limit` (default 50, max 200), NOT by `detail`; for a 'full list' of titles, raise `limit` and keep detail='short'.

List all brands on your PostKing account. Returns id+name+website by default (short). Use detail='medium' for description, 'full' for all raw fields. To zoom into one brand call get_brand_info with detail='full'.

List all custom domains for the active brand. Lists default short; pass detail=medium/full for more fields including SSL status, verification, and connected blogs or landing pages.

To check a SPECIFIC operation's status, call get_job with its operationId — this list only returns the most recent ops and may omit a just-started one. List background jobs for the active brand. Use status='pending' to see in-flight ops, 'completed' to see finished ones. Use get_job with an operationId to poll a specific job — most async tools return an operationId. Supports detail param: short=id+kind+state, medium=6 key fields, full=raw.

Lists landing pages. Default detail='short' (id/slug/name/status). Use view_landing_page for full content.