Linkedctl

io.github.alexey-pelykhPublished by GitHub account alexey-pelykhv0.5.0Updated Oct 25, 2026

CLI and MCP server for the LinkedIn API

VerifiedSTDIODesktop onlyCommunication & CollaborationData & Analytics

Overview

AI-generated overview

A local MCP server and CLI for the LinkedIn API that lets an assistant publish posts, manage comments and reactions, and read analytics.

What you can do
Create, read, update and delete LinkedIn posts, including drafts, images, video, documents, articles, carousels and polls, as yourself or an organization. Create, list, get and delete comments, and add, list or remove reactions on posts. List organizations you administer, fetch organization details and follower counts. Read per-post, per-member and per-organization analytics. Upload images, video and documents, and check identity and authentication status.
When to use it
Useful when you want an assistant to draft and publish LinkedIn content, manage engagement on posts, or pull post and organization statistics without leaving the chat. Suited to social media and content workflows for personal or organization accounts.
Requirements
Local process run via npx or a global npm install; Node.js 24 or newer. A LinkedIn Developer App with OAuth 2.0 credentials, or a direct access token. Credentials can come from LINKEDCTL_CLIENT_ID, LINKEDCTL_CLIENT_SECRET and LINKEDCTL_ACCESS_TOKEN, or from YAML config files; LINKEDCTL_API_VERSION is required. Network access to LinkedIn.
Before you install
Holds LinkedIn OAuth credentials and access tokens in environment variables or YAML config files, so protect those files and variables. Tools can publish public posts, comment, react and delete posts or comments, which changes data on a live LinkedIn account; deletions require confirmation in the CLI but check what the assistant is about to do. Content and media are sent to LinkedIn.

Installation

In SourceWeft

  1. Open Linkedctl in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[LinkedCtl: The Complete CLI & MCP for LinkedIn]

[CI] [CodeQL] [License]

OAuth2 CLI and MCP server for the LinkedIn API.

What It Does

  • Post content — text, images, video, documents, articles, multi-image carousels, and polls
  • Comments & reactions — create, list, and delete comments and reactions on posts
  • Organization support — post, comment, react, and view analytics as an organization
  • Analytics — per-post, per-member, and per-organization statistics
  • Media uploads — upload images, video, and documents to LinkedIn
  • Draft posts — save posts as drafts before publishing
  • OAuth 2.0 authentication with your own LinkedIn app
  • Direct token passing for tokens obtained from other applications
  • MCP server for AI assistant integration (Claude, Cursor, etc.)
  • CLI for scriptable LinkedIn operations

Prerequisites

Installation

sh
npm install -g linkedctl

Or run directly:

sh
npx linkedctl --help

Quick Start

  1. Create a LinkedIn app at linkedin.com/developers
  2. Configure OAuth 2.0 credentials
  3. Authenticate:
    sh
    linkedctl auth login --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
  4. Start using:
    sh
    linkedctl post "Hello from LinkedCtl!"

See the OAuth Setup Guide for detailed step-by-step instructions.

MCP Integration

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

json
{    "mcpServers": {        "linkedctl": {            "command": "npx",            "args": ["linkedctl", "mcp"]        }    }}
Claude Code
sh
claude mcp add linkedctl -- npx linkedctl mcp
Cursor

Add to .cursor/mcp.json in your project root:

json
{    "mcpServers": {        "linkedctl": {            "command": "npx",            "args": ["linkedctl", "mcp"]        }    }}
Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

json
{    "mcpServers": {        "linkedctl": {            "command": "npx",            "args": ["linkedctl", "mcp"]        }    }}

Available Tools

All tools accept an optional profile parameter to select a configuration profile.

Authentication
ToolDescription
whoamiShow the current user's name, email, and profile picture URL
auth_statusShow authentication status for a profile
auth_revokeRevoke the access token server-side and clear local credentials
Posts
ToolDescription
post_createCreate a post on LinkedIn with optional media, poll, or article attachment
post_getFetch a single post by URN
post_listList posts with pagination (supports as_org for organization posts)
post_updateUpdate the commentary text of an existing post
post_deleteDelete a post by URN

post_create supports rich content types:

ParameterDescription
textPost text content (required)
visibilityPUBLIC or CONNECTIONS (default PUBLIC)
draftSave as draft instead of publishing
image / image_fileAttach a single image (URN or local file path)
video / video_fileAttach a video (URN or local file path)
document / document_fileAttach a document (URN or local file path)
images / image_filesAttach multiple images (minimum 2)
article_urlAttach an article link
pollPoll question text
poll_optionsPoll answer options (2–4 required when poll is set)
poll_durationONE_DAY, THREE_DAYS, ONE_WEEK, or TWO_WEEKS
as_orgPost as an organization (numeric ID)
Comments
ToolDescription
comment_createCreate a comment on a post (supports as_org)
comment_listList comments on a post
comment_getGet a specific comment by URN
comment_deleteDelete a comment by URN
Reactions
ToolDescription
reaction_createAdd a reaction to a post (supports as_org). Types: LIKE, PRAISE, EMPATHY, INTEREST, APPRECIATION, ENTERTAINMENT
reaction_listList reactions on a post
reaction_deleteRemove a reaction from a post (supports as_org)
Organizations
ToolDescription
org_listList organizations the authenticated user administers
org_getFetch a single organization by ID
org_followersGet the follower count for an organization
Analytics
ToolDescription
stats_postGet analytics for a single post (impressions, reach, reactions, comments, reshares)
stats_meGet aggregated analytics across all your posts
stats_orgGet share statistics for an organization (lifetime or time-bucketed)
Media
ToolDescription
document_uploadUpload a document to LinkedIn (PDF, DOCX, PPTX, DOC, PPT; max 100 MB)

Configuration

Config File Format

LinkedCtl stores configuration in YAML files. Each file represents a single profile:

yaml
api-version: "202601"oauth:    client-id: "YOUR_CLIENT_ID"    client-secret: "YOUR_CLIENT_SECRET"    access-token: "YOUR_ACCESS_TOKEN"    refresh-token: "YOUR_REFRESH_TOKEN"    token-expires-at: "2026-05-03T12:00:00.000Z"

Available keys:

KeyDescription
api-versionLinkedIn API version (e.g. 202601)
oauth.client-idOAuth 2.0 client ID
oauth.client-secretOAuth 2.0 client secret
oauth.access-tokenOAuth 2.0 access token
oauth.refresh-tokenOAuth 2.0 refresh token
oauth.token-expires-atToken expiration timestamp (ISO 8601)

Config files are written with 0600 permissions (owner read/write only).

File Location and Precedence

Without a profile, LinkedCtl searches for config files in this order:

  1. .linkedctl.yaml in the current working directory
  2. ~/.linkedctl.yaml in the home directory

The first file found is used. When writing (e.g. after auth login), LinkedCtl writes to the CWD file if it exists, otherwise to the home directory file.

Profiles

Profiles let you manage multiple LinkedIn accounts or configurations. Each profile is stored as a separate YAML file under ~/.linkedctl/:

ProfileConfig file path
(default)~/.linkedctl.yaml
work~/.linkedctl/work.yaml
personal~/.linkedctl/personal.yaml

Use the --profile flag with any command:

sh
linkedctl --profile work auth login --client-id ID --client-secret SECRETlinkedctl --profile work post "Hello from my work account!"

Manage profiles with the profile command:

sh
linkedctl profile create work --access-token YOUR_TOKEN --api-version 202601linkedctl profile listlinkedctl profile show worklinkedctl profile delete work

Authentication Methods

OAuth 2.0 (Recommended)

LinkedCtl supports OAuth 2.0 with your own LinkedIn Developer App:

sh
linkedctl auth login --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
Direct Token

If you already have an access token from another application:

sh
linkedctl auth token --access-token YOUR_TOKEN

Environment Variables

VariableDescription
LINKEDCTL_CLIENT_IDLinkedIn OAuth 2.0 client ID
LINKEDCTL_CLIENT_SECRETLinkedIn OAuth 2.0 client secret
LINKEDCTL_ACCESS_TOKENDirect access token (bypasses OAuth flow)
LINKEDCTL_API_VERSIONLinkedIn API version string (e.g. 202601) required

Environment variables take precedence over config file values.

Profile-Prefixed Environment Variables

When using a named profile, LinkedCtl also reads profile-prefixed environment variables. The profile name is uppercased with hyphens converted to underscores:

ProfileVariable
(default)LINKEDCTL_ACCESS_TOKEN
workLINKEDCTL_WORK_ACCESS_TOKEN
my-brandLINKEDCTL_MY_BRAND_ACCESS_TOKEN

The same pattern applies to CLIENT_ID, CLIENT_SECRET, and API_VERSION.

Precedence Order

Configuration values are resolved in this order (highest priority first):

  1. Environment variables (profile-prefixed if a profile is active)
  2. Config file (profile-specific file, or CWD/home fallback)

CLI Reference

Global Options

OptionDescription
--profile <name>Use a specific configuration profile
--jsonForce JSON output
-q, --quietSuppress informational output
--no-colorDisable color output

auth — Manage Authentication

CommandDescription
auth setupConfigure OAuth client credentials interactively
auth loginAuthenticate via OAuth 2.0 (opens browser)
auth tokenStore a direct access token
auth statusShow authentication status and token expiry
auth logoutClear stored credentials from the active profile
auth refreshRefresh the access token using a stored refresh token
auth revokeRevoke the access token server-side and clear local tokens

auth login options:

OptionDescriptionDefault
--client-id <id>OAuth 2.0 client IDfrom config
--client-secret <secret>OAuth 2.0 client secretfrom config
--scope <scopes>OAuth 2.0 scopes (space-separated)openid profile w_member_social

auth token options:

OptionDescription
--access-token <token>Access token to store (required)

post — Manage LinkedIn Posts

sh
# Shorthand: pass text as an argumentlinkedctl post "Hello from LinkedCtl!"
# Explicit subcommandlinkedctl post create --text "Hello from LinkedCtl!"
# Pipe content from stdinecho "Hello from LinkedCtl!" | linkedctl post create
CommandDescription
post createCreate a post on LinkedIn
post get <urn>Fetch a post by URN
post listList posts with pagination
post update <urn>Update a post's commentary text
post delete <urn>Delete a post (with confirmation)

post create options:

OptionDescriptionDefault
--text <text>Text content (also accepts --text-file, positional, or stdin)
--visibility <visibility>PUBLIC or CONNECTIONSPUBLIC
--draftSave as draft instead of publishing
--image <urn>Image URN to attach
--image-file <path>Local image file to upload and attach
--video <urn>Video URN to attach
--video-file <path>Local video file to upload and attach
--document <urn>Document URN to attach
--document-file <path>Local document file to upload and attach
--images <urns>Multiple image URNs (comma-separated, minimum 2)
--image-files <paths>Multiple local image files (comma-separated, minimum 2)
--article-url <url>Article URL to attach
--poll <question>Poll question text
--option <text>Poll option (repeat 2–4 times)
--poll-duration <duration>ONE_DAY, THREE_DAYS, ONE_WEEK, or TWO_WEEKSTHREE_DAYS
--as-org <id>Post as an organization (numeric ID)
--format <format>Output format (json, table)auto

post list options:

OptionDescriptionDefault
--count <n>Number of posts to return (max 100)10
--start <n>Starting index for pagination0
--as-org <id>List posts of an organization (numeric ID)

comment — Manage Comments

CommandDescription
comment create <post-urn>Create a comment on a post
comment list <post-urn>List comments on a post
comment get <comment-urn>Get a specific comment by URN
comment delete <comment-urn>Delete a comment (with confirmation)

comment create options:

OptionDescription
--text <text>Comment text (required)
--as-org <id>Comment as an organization (numeric ID)

reaction — Manage Reactions

CommandDescription
reaction create <urn>Add a reaction to a post
reaction list <urn>List reactions on a post
reaction delete <urn>Remove a reaction from a post

reaction create options:

OptionDescription
--type <type>LIKE, PRAISE, EMPATHY, INTEREST, APPRECIATION, or ENTERTAINMENT (default LIKE)
--as-org <id>React as an organization (numeric ID)

org — Manage Organizations

CommandDescription
org listList organizations the authenticated user administers
org get <id>Get organization details
org followers <id>Get organization follower count

media — Upload Media

CommandDescription
media upload-image <file>Upload an image (JPG, PNG, GIF)
media upload-video <file>Upload a video
media upload-document <file>Upload a document (PDF, DOCX, PPTX, DOC, PPT; max 100 MB)

All media commands accept --as-org <id> and --format json|table.

stats — View Analytics

CommandDescription
stats post <urn>Get post analytics (impressions, reach, engagement)
stats meGet aggregated analytics across all your posts
stats org <id>Get organization share statistics

Common options:

OptionDescription
--from <date> / --start <date>Start of date range (YYYY-MM-DD)
--to <date> / --end <date>End of date range (YYYY-MM-DD)
--time-granularity <granularity>DAY or MONTH (org stats only)

profile — Manage Configuration Profiles

CommandDescription
profile create <name>Create a new profile
profile listList all profiles
profile show [<name>]Show profile details (redacted)
profile delete <name>Delete a profile (with confirmation)

profile create options:

OptionDescription
--access-token <token>OAuth 2.0 access token (required)
--api-version <version>LinkedIn API version, e.g. 202601 (required)

whoami — Show Current User

sh
linkedctl whoamilinkedctl whoami --format json
OptionDescriptionDefault
--format <format>Output format (json, table)auto

completion — Shell Completions

sh
linkedctl completion bashlinkedctl completion zsh

Security

  • Dependabot keeps dependencies up to date with automated pull requests
  • CodeQL analysis runs on every push and pull request for automated vulnerability detection
  • Path traversal validation on profile names prevents directory escape attacks
  • Unified auth error handling across all MCP tools provides consistent authentication failure messages
  • Destructive operations (delete post, delete comment, delete profile) require interactive confirmation unless --force is passed

Disclaimer

This is an independent project and is not affiliated with, endorsed by, or associated with LinkedIn Corporation. LinkedIn is a trademark of LinkedIn Corporation.

License

AGPL-3.0-only

Using LinkedCtl as a CLI tool or MCP server: No license obligations — use freely.

Using @linkedctl/core as a library in your project: Your combined work must be licensed under AGPL-3.0 (or a compatible license).

Source: README.md at commit d8622c0

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.5.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts