PerfectPost MCP — User Guide

PerfectPost exposes an MCP server that gives access to your LinkedIn posts: content, statistics, drafts, and scheduling. It connects in a single command from Claude Code.

1. Setup (one-time)

Add the MCP server to Claude Code with this command:

claude mcp add --transport http --scope user \
  --client-id dnakgf4sbal93ukngisqgb3vo \
  --callback-port 6274 \
  perfectpost https://mcp.perfectpost.social/mcp

Both --client-id and --callback-port are required: the PerfectPost server does not support automatic OAuth client registration, and the callback port must be fixed (6274) to match the authorized redirect URLs.

On first use, type /mcp in Claude Code, select "Authenticate" to start the OAuth flow. Your browser will open for you to log in with your PerfectPost account. Once authenticated, the token is stored automatically.

Verify the server is added:

claude mcp list

2. Available Tools

Reading posts

Draft management and scheduling

3. Data Formats

Posts (get_post)

Each post returns an object with these key fields:

urn          — LinkedIn identifier (e.g. "urn:li:share:123456789")
text         — plain text content of the post
date         — ISO publication date
type         — post type (nullable)
media        — media object: { type: "image"|"video"|"pdf"|"poll", url, thumbnailUrl }
favorite     — boolean
objective    — marketing objective: "tofu" | "mofu" | "bofu" | null
categories   — array of tags
latestStats  — metrics (see below)

Performance metrics (latestStats)

All stat fields use the num* prefix and are nullable:

numLikes               — number of likes
numImpressions         — total impressions
numUniqueViews         — unique views
numComments            — number of comments
numShares              — number of shares
numSaves               — number of saves
numProfileViewsFromPost — profile views generated by this post
numFollowersFromPost   — followers gained via this post
numVideoViews          — video views (if applicable)
videoWatchTime         — total watch time (string)
averageVideoWatchTime  — average watch time (string)
engagementRate         — overall engagement rate (number, nullable)
numVoters              — voters if poll
numArticleViews        — article views if applicable
numSentOnLinkedin      — LinkedIn sends

Drafts (get_draft / create_draft)

id              — internal identifier (string)
status          — "draft" | "scheduled" | "published"
title           — optional title (nullable)
content         — content in HTML (not plain text)
date            — ISO creation date
programmingDate — ISO scheduling date (nullable) — field to use with schedule_draft
isPublished     — boolean
urn             — LinkedIn URN if already published (nullable)
objective       — "tofu" | "mofu" | "bofu" | null
categories      — array of tags
firstComment    — first comment to publish automatically (nullable)
media           — { type: "image"|"video"|"pdf"|"images"|"poll", url/urls, ... }

Important: draft content is HTML. When creating or editing a draft, format text with HTML tags (<p>, <br>, etc.).

Profile (get_linkedin_profile)

Nested structure:

identity    — { firstname, lastname, email, headline, vanityName, profileUrl, summary, locale, timeZone }
linkedin    — { picture, backgroundPicture, isConnected }
preferences — { defaultPublishTime, appearanceMode, autoSaveDraftsEnabled }
statistics  — { totalPosts, totalDrafts, totalPublished, totalScheduled }
account     — { createdAt, lastLogin }

4. Example Prompts

Analyzing performance

Show me the statistics for my LinkedIn posts from last month.
Which posts performed best?

Give me a summary of my LinkedIn engagement over the last 3 months:
impressions, likes, comments. Present it as a table.

Who has engaged most with my recent posts?

Writing and scheduling content

Write a LinkedIn post about [topic] in my style, based on my last 5 posts.
Create a draft and schedule it for tomorrow at 9am.

Here is an article I wrote: [text]. Turn it into a compelling LinkedIn post,
create the draft and schedule it for Friday at 8:30am.

Content search and analysis

Find all my posts that mention [topic].
Which ones had the most engagement?

Tip: search_posts does exact string matching — prefer specific keywords ("ChatGPT", "DeepSeek") over generic terms ("AI"). Run multiple searches with different keywords for full coverage.

5. Usage Tips

For scheduling, always specify the desired date and time. The field to set in schedule_draft is programmingDate (ISO date).

For statistics, you can request comparisons over any period: "last month vs the month before", "this year", "the last 30 days". Key metrics are numImpressions, numLikes, numComments, engagementRate.

To create content in your style, start by reading your recent posts (list_posts + get_post) before generating a new draft — this produces much better results.

Media: if you want to attach an image to a draft, host it somewhere and give the URL to Claude — it will use set_draft_media_from_url. Supported types are image, video, pdf, and images (gallery).

Marketing objectives: you can tag your posts with a tofu (awareness), mofu (consideration), or bofu (conversion) objective — useful for filtering and analyzing by funnel stage.

6. Troubleshooting

"Unauthorized" / expired token: restart Claude Code, the token will be renewed automatically.

Server doesn't appear in claude mcp list: re-run the installation command from step 1.

Stats not loading: verify that your LinkedIn account is connected to PerfectPost at perfectpost.social.