English | 简体中文

Octopus LinkedIn

Part of Octopus Core — the open infrastructure stack for governed AI. One job per repo, along the agent lifecycle: Scout · Observe · Experience · Blackboard · Runtime · Replay — with Inspect governing every stage.

This repo — LinkedIn · Governance example: The stack’s draft→approve→publish discipline, applied to a real outward action.

Governed LinkedIn marketing over MCP. Draft, review, publish, comment, and read engagement on LinkedIn — from Claude Desktop, Claude Code, or any MCP-compatible agent — using the official LinkedIn API.

Most "LinkedIn AI" tooling stops at writing the post. The obvious next step is publishing it — and that's where you want governance, not a black box. Octopus LinkedIn makes the whole loop explicit:

draft → review → approve → publish → comment → analyze

Drafting and approving are local-only — they never touch the network. publish_draft is the default gate that sends content out, and it refuses to publish a draft that hasn't been explicitly approved. Direct MCP publish/delete/ reply tools are disabled by default unless you opt in with OCTOPUS_LINKEDIN_ALLOW_DIRECT_TOOLS=1.

Tools

By default the MCP server exposes the draft-review-publish path plus read-only tools. Direct outbound tools below are available only after the explicit opt-in flag above.

Content intelligence (LLM-backed)

Conditioned on your brand voice; everything stays behind the approval gate.

Plus MCP prompts (draft_post, repurpose_article, reply_to_comments) and resources (voice://profile, drafts://list) so MCP clients get task templates and live context, not just raw tool calls.

Scope note: the official API only lets you comment on content you control (your own posts, or an org Page you admin). It cannot auto-comment on arbitrary third-party posts — by design. See docs/ARCHITECTURE.md.

LLM configuration

Set one provider and its key in the private app config file:

LLM_PROVIDER=anthropic       # anthropic | openai | gemini
ANTHROPIC_API_KEY=sk-ant-... # or OPENAI_API_KEY / GEMINI_API_KEY
# LLM_MODEL=claude-sonnet-4-6  # optional override

Quick start

1. Install

pip install octopus-linkedin

This installs two commands: octopus-linkedin (CLI) and octopus-linkedin-mcp (the MCP server). To work on the project from source instead, see Development.

2. Create a LinkedIn app

At linkedin.com/developers, create a Standalone app tied to a Company Page, then add these products:

• Share on LinkedIn → grants w_member_social (posting)
• Sign In with LinkedIn using OpenID Connect → grants openid profile email

In the app's Auth tab, add an authorized redirect URL:

http://localhost:8000/callback

3. Configure

octopus-linkedin init-config

Edit the printed config path and paste your Client ID and Client Secret (Auth tab). The config file is created with 0600 permissions outside the source tree by default.

4. Authorize (one time)

python -m linkedin.auth

This opens your browser; log in and approve. A token is cached under the local app data directory with 0600 permissions. Member tokens last ~60 days; re-run this when it expires.

5. Run

python server.py

Connect to Claude Code

claude mcp add octopus-linkedin -- octopus-linkedin-mcp

Or add it to your MCP client config:

{
  "mcpServers": {
    "octopus-linkedin": {
      "command": "octopus-linkedin-mcp"
    }
  }
}

Then just ask: "Draft a LinkedIn post about X, let me review it, then publish."

Example workflow

1. create_draft — "Save this post about our launch."
2. list_drafts / get_draft — review the wording.
3. approve_draft — sign off.
4. publish_draft — it goes live (and only now).
5. get_post_stats — check likes and comments later.

CLI

The same engine ships as a CLI for scripting and cron:

octopus-linkedin authorize
octopus-linkedin post "Hello, world" --visibility PUBLIC
octopus-linkedin draft "A post to review later"
octopus-linkedin drafts --status approved
octopus-linkedin approve drft_abc123 --note "lgtm"
octopus-linkedin schedule drft_abc123 2026-07-02T09:00:00Z
octopus-linkedin run-scheduler --interval 60     # loop: publish due drafts
octopus-linkedin stats urn:li:share:123

Scheduling

Scheduling is split so nothing publishes by surprise: you schedule_draft an approved draft for a future UTC time, then a runner actually sends it when due. Run the runner one of three ways:

• octopus-linkedin run-scheduler — a simple foreground loop, or
• octopus-linkedin publish-due from cron every few minutes, or
• the publish_due MCP tool on demand.

Only drafts that are both approved and past their time are published.

Development

pip install -e ".[dev]"
ruff check . && ruff format --check . && pytest

See CONTRIBUTING.md.

Roadmap

Shipped:

• Scheduled publishing (publish an approved draft at a future time)
• Multi-image posts (up to 9)
• A standalone CLI alongside the MCP server
• Bilingual docs (English | 简体中文)

Content-intelligence layer (shipped):

• LLM backend — Anthropic / OpenAI / Gemini (write / polish / optimize)
• MCP prompts + resources surface
• Draft-from-URL / article repurposing (SSRF-guarded)
• Brand-voice memory (conditions every generation)
• Comment triage on your own posts (classify → draft reply → approve)
• A/B variant generation

Gated (need LinkedIn approval), tracked but not built:

• Company Page posting & engagement (Community Management API)
• Impressions / reach via memberCreatorPostAnalytics (partner-gated, 2025)
• PDF/document posts (need the versioned /rest/posts + Documents API)

Contributions to any of these are welcome.

Security

The private config file and OAuth token cache live outside the source tree by default. See SECURITY.md for reporting and credential handling.

License

Apache-2.0.