io.github.bitsandtea/postking-mcp

Add a new custom domain to the active brand. After adding, call verify_domain to check DNS and activate it.

Approve and schedule a draft post. Requires a future datetime. The scheduledAt must be an ISO 8601 UTC datetime, e.g. 2026-03-11T09:00:00Z. After approving, the post status becomes 'scheduled'.

List available credit packs for one-off top-ups. Returns all packs with their SKU, price in USD, and credit amount. Call this tool first to show the user their options, then ask which pack they want. Only after the user explicitly chooses a pack, call billing_topup with that packSku.

List available PostKing subscription tiers (GROWTH, PRO, ENTERPRISE). Returns each tier's name, price in USD, monthly credits, and billing interval options. Use billing_subscribe to create a subscription Checkout session for a chosen tier.

Create a Stripe Checkout session for a PostKing subscription. Returns { checkoutUrl, sessionId, tier, interval, amountUsd }. Subscription credits refill User.credits each billing period. The subscription Checkout is best completed by a human; the Link virtual card covers the first invoice only (renewals need a durable payment method).

Top up credits by charging the account's card on file (Stripe off-session). Prefers the headless path — no checkout link required. IMPORTANT: Only call this tool after the USER has explicitly chosen a specific pack — it triggers a real charge. To show the user their options first, call billing_list_packs and present the results; do NOT pick a pack on the user's behalf. The response is ONE OF two shapes: (1) Headless success (default when a card is on file): { status: 'paid', paymentIntentId, amountUsd, credits, balance, packSku, cardLast4/receiptUrl when available }. When you receive status === 'paid', the payment has already completed and the credits are in the wallet NOW. Announce to the user: payment ID, last-4 card digits, credits added, and new balance. You are DONE — do NOT call billing_wallet to poll. (2) Checkout fallback (only when there is no card on file): { checkoutUrl, sessionId, amountUsd, credits, packSku }. When you receive checkoutUrl, hand that link to the user so they can complete payment in their browser. Valid skus: agent_4 ($4 / 160 credits), agent_5 ($5 / 220 credits), agent_25 ($25 / 1200 credits), agent_50 ($50 / 2600 credits).

Fetch the user's credit balance and recent usage entries. Returns { credits, recent } where recent is the last ~10 usage rows. Poll this to confirm a top-up landed ONLY after a billing_topup CHECKOUT result (one that returned a checkoutUrl), until credits rise. Do NOT poll after a status:'paid' headless top-up — those credits are already applied and the new balance is in the topup response.

Capture brand truths from plain natural-language text. Describe facts/observations about the brand in ordinary prose — a sentence or short paragraph (≤8000 chars). Do NOT pre-classify, pre-format, or guess the taxonomy: PostKing's LLM extraction pipeline reads the text and decides which atomic 'brand truths' to persist and which to skip (duplicates, too vague, or previously rejected facts). Returns { addedCount, skippedCount, added, skipped }: 'added' are the truths that were stored; 'skipped' lists each rejected quote with a reason. Review both — the skipped reasons tell you what didn't make it in and why.

Delete a brand truth by ID. This also records rejection memory: the system learns to stop re-suggesting that fact during future extractions. Use it deliberately — deleting a truth teaches PostKing that the fact should not come back.

Fetch a single brand truth by ID. short {id,name,type,pinned}; medium adds personaScope+tags+summary+timestamps; full = raw (includes full content). Use detail='full' to retrieve the complete content body.

List the brand's stored brand truths (atomic facts/observations used to ground generation). short {id,name,type,pinned}; medium adds personaScope+tags+summary+timestamps; full = raw. Filter by type, personaScope, tags (array or comma-separated), or a free-text query.

Targeted edit of an existing, known brand truth (by ID). This does NOT re-run the LLM extraction pipeline — it writes the provided fields directly. Use it to correct wording (name/description/content), fix the type/personaScope, adjust tags, or pin/unpin. To capture NEW facts from prose, use brand_truth_create instead.

Cancel a scheduled or approved post, reverting it to draft status without deleting it. Use delete_post to remove it entirely.

Check whether text is likely AI-generated. Returns a score and analysis.

List all connected and disconnected social accounts for the active brand. Lists default short; pass detail=medium/full for more fields. Run before posting to confirm platform availability.

Remove the selected visual from a post for a specific platform. Includes editInVisualEditor: a direct URL to edit the post in the visual editor (when active brand is set).

Async. Batch-add competitor domains (1–20) to the brand. Returns { operationId, status } — poll get_job until state=completed. Each domain triggers crawl + profile analysis. Typically takes ~2–5 min.

Async. Trigger analysis for existing BrandCompetitor rows that are pending or failed. Use competitor_add to create new rows; use this to retry failed ones. Returns { operationId, status } — poll get_job until state=completed. Typically takes ~2–5 min.

List the data sources used to build the brand's competitive comparison. Returns raw source records (URLs, snippets, timestamps) — useful for auditing comparison accuracy.

Soft-delete a tracked competitor from the brand. No credits are refunded. Use competitor_update (empty body) to restore.

Async. Generate the competitive landscape overview (uses ~20 credits). Returns { operationId, status } — poll get_job until state=completed. Typically takes ~2–5 min.

Get the brand's head-to-head competitive comparison. short {id,status,generatedAt,competitorCount}; medium adds summary+strengths+weaknesses; full = raw. Returns null when no comparison has been generated yet — use competitor_recompute_comparison to generate.

Get the brand's competitive landscape overview. short {id,status,generatedAt}; medium adds summary excerpt; full = raw. Returns null when no overview exists — use competitor_generate_overview to create one.

List the brand's tracked competitors. short {id,domain,analysisState}; medium adds source,creditsCharged,lastError,addedAt,lastCrawledAt,cacheSource; full = raw. Also returns a dashboard link to the Competitors tab.

Start a competitor discovery probe. PostKing crawls the web to find rival domains automatically. Returns { started: true } when kicked off, or { alreadyRan, status } when a probe result already exists. Poll competitor_probe_status to check readiness, then use competitor_probe_classify to accept/reject candidates.

Classify a discovered (or manually added) competitor candidate. 'direct' seeds a BrandCompetitor row; 'similar' and 'not_relevant' update the probe JSON only. Call once per domain. Probe must be in completed state first. Returns { candidates } — the updated full candidate list.

Check the status of the competitor discovery probe. Returns { status, candidates? } — status is one of: pending | running | completed | failed. When completed, candidates contains the discovered domains ready for classification.

Trigger a fresh head-to-head comparison recompute. Use after adding or re-analyzing competitors to get an up-to-date comparison.

Async. Refresh all active competitors for the brand (re-crawl + re-profile). Returns { operationId, status } — poll get_job until state=completed. Typically takes ~2–5 min.

Update a competitor's settings. Currently supports toggling excludeFromSeoPull (removes the domain from keyword-gap pull without deleting it). Send an empty body to restore a soft-deleted competitor.

Connect a verified domain to a blog publication so articles are served from that domain.

Create a new PostKing API key. The raw token (pk_live_*) is returned ONCE in this response and never shown again. Store it immediately — treat it like a password. Scope: 'write' (default) or 'read'.

Create a new author for blog articles. Returns an authorId that can be used in generate_blog_post and update_blog_article.

Create a new category in a blog publication.

STEP 1 of brand onboarding (manual path — no website crawl). Creates a new brand from user-supplied name/description, sets it as active, then RETURNS a `nextStep` payload telling you to ask the user which platforms they publish on. After the user answers, call `set_brand_mediums` with their picks. Ask the user for a description if they did not provide one — onboarding will fail without it.

Create a comparison / 'X vs Y' / 'best <category>' page for the brand WITHOUT going through the full SEO cluster → brief flow. One call kicks off generation, then this tool polls until the page is built and returns its slug(s) + link. `mode` controls the engine: 'research' crawls the named competitors + live SERP results before writing — slower (can take several minutes) but produces the strongest, best-grounded page; 'simple' skips all crawling and lets the LLM author from what you provide — fast, best when you already have the facts or just want a quick draft. When your inputs are sparse (few/no options, no domains, no seedData), prefer 'research' — it will discover and ground the comparison for you and yield a far stronger page than 'simple'. `seedData` (simple mode): paste your own raw facts/notes/competitor details here and the LLM writes from them instead of crawling — this is how you feed your own data and avoid a crawl. Async — fires the create, then polls the operation up to ~5 min. On success returns { briefId, sidePageId, sidePageSlug, landingPageSlug, webUrl, warnings }. If it is still running after the wait, returns { status: 'still_generating', operationId } — poll get_job with that operationId until state is 'completed'; do NOT fabricate the page yourself. Any `warnings` are surfaced verbatim — relay them to the user (e.g. sparse-input notes such as 'research mode would produce a stronger page').

Save a post draft with custom content to one or more platforms. Supported platforms: x, linkedin, instagram, threads, facebook. After creating, call approve_post with a future ISO 8601 datetime to schedule it. To check which platforms are connected first, call check_social_accounts. Each created post includes editInVisualEditor: a direct URL to edit it in the visual editor.

Create a new blog publication (the container that articles live under). Returns a publicationId needed for generate_blog_post.

Return a clickable browser link to a PostKing dashboard page. ALWAYS use this instead of guessing dashboard URLs. The SEO roadmap / content plan is section 'seo_briefs' (or 'seo' for the overview) — there is NO '/seo/roadmap' page.

Soft-delete an asset from the brand library. Pass confirm: true to proceed.

Permanently delete a blog article.

Remove a custom domain. Connected blogs and landing pages are unlinked but not deleted.

Permanently delete a landing page. Pass confirm: true to proceed — this is irreversible.

Cancel and delete a post regardless of its current status (draft, scheduled, or posted).

Delete a side page. Pass confirm: true to proceed.

Delete a content theme from the active brand.

Permanently remove the weekly schedule for the active brand. Pass confirm: true to proceed.

Pause the weekly content schedule without deleting it. Re-enable later with enable_weekly_schedule.

Disconnect a social account by its account ID.

Async LLM ai-edit of the brand's audience/ICP. Describe the change in `prompt` (natural language). `sections` is REQUIRED — the audience section(s) to edit (e.g. 'demographics', 'painPoints', 'positioning'). If unsure which sections are valid for this brand, call preview_audience_edit first and use the section keys it returns. Returns { operationId, status } — poll get_job(operationId) until state is 'completed' (or 'failed'/'cancelled' on error). Only one audience edit can run at a time; a second call returns an 'already_running' notice. Typically takes ~30–90 s.