企业官网建设流程全解析

Klavis LinkedIn MCP Server 实践指南：OAuth 鉴权、Docker 自托管与内容发布全流程

【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis

本篇技术指南以开源仓库 mcp_servers/linkedin/README.md 为主体，结合 server.py、tools/ 等源码实现，完整讲解基于 Klavis AI 的 LinkedIn MCP Server 的两种部署方式（托管服务与 Docker 自托管）、OAuth 鉴权机制、四个可调用工具的参数与底层调用链。读完你可以直接接入 LinkedIn 官方 API，用 AI Agent 自动读取个人资料、发布带话题标签的图文帖子、分享带元数据预览的链接，并理解令牌如何从请求头一路传递到api.linkedin.com。

一、LinkedIn MCP Server 是什么

LinkedIn MCP Server 是一个基于 Model Context Protocol（MCP）的服务端实现，让 AI Agent 通过标准化的 MCP 工具调用 LinkedIn 官方 API（api.linkedin.com/v2），从而完成专业资料管理、帖子发布、内容分享与职业社交自动化。其核心能力来自两点：

• 统一鉴权：支持 OAuth 流程，既可通过 Klavis AI 托管服务自动完成 OAuth，也可在自托管时通过AUTH_DATA或LINKEDIN_ACCESS_TOKEN环境变量注入访问令牌；
• 标准协议：基于官方mcpPython SDK 实现（requirements.txt固定mcp==1.11.0），对外暴露 SSE 与 StreamableHTTP 双传输端点，任意 MCP 兼容客户端（Claude Desktop、Cursor、VS Code 等）均可直接接入。

仓库源码中该服务器名为linkedin-mcp-server，Docker 镜像为ghcr.io/klavis-ai/linkedin-mcp-server，默认监听5000端口（见 Dockerfile 中的EXPOSE 5000与 server.py 中端口环境变量的默认值）。

二、30 秒快速启动：托管服务与 SDK 接入

README 推荐的“30 秒启动”路径是使用 Klavis AI 托管基础设施，无需任何服务端搭建，只需一个免费 API Key：

pip install klavis # 或 npm install klavis

from klavis import Klavis klavis = Klavis(api_key="your-free-key") server = klavis.mcp_server.create_server_instance("LINKEDIN", "user123")

其中user123是用户标识，用于区分 Klavis 侧“谁连接了哪些账号”的数据隔离。第二个参数对应文档中强调的userId语义——它应当是本人、团队或组织的唯一标识。

2.1 进阶：通过 Strata 服务器创建并完成 OAuth

官方文档 提供了更完整的 Strata 接入流程，适合需要编程式管理 OAuth 与多个集成的场景：

from klavis import Klavis from klavis.types import McpServerName klavis_client = Klavis(api_key="YOUR_API_KEY") response = klavis_client.mcp_server.create_strata_server( servers=[McpServerName.LINKEDIN], user_id="user123" ) import webbrowser # 打开 OAuth 授权页面，完成 LinkedIn 账号授权 webbrowser.open(response.oauth_urls[McpServerName.LINKEDIN])

TypeScript 等价写法：

import { KlavisClient, Klavis } from 'klavis'; const klavis = new KlavisClient({ apiKey: process.env.KLAVIS_API_KEY! }); const response = await klavis.mcpServer.createStrataServer({ servers: [Klavis.McpServerName.LinkedIn], userId: "user123" }); // 在浏览器中打开 response.oauthUrls[Klavis.McpServerName.LinkedIn] 完成授权

也可以直接通过 REST 创建：

curl -X POST "https://api.klavis.ai/mcp-server/strata/create" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "servers": ["LinkedIn"], "userId": "user123" }'

授权完成后，服务器会返回一个可直接用于任意 MCP 客户端的 endpoint URL。OAuth URL 还支持自定义scope与redirect_url参数，以满足精细化权限与回调控制需求。

三、Docker 自托管：两种鉴权模式

需要自行掌控数据面时，README 提供了两条 Docker 运行路径。

3.1 OAuth 模式（生产推荐）

通过KLAVIS_API_KEY交给 Klavis AI 处理完整的 OAuth 流程，无需自己维护令牌：

docker pull ghcr.io/klavis-ai/linkedin-mcp-server:latest # 通过 Klavis AI 自动处理 OAuth docker run -p 5000:5000 -e KLAVIS_API_KEY=$KLAVIS_API_KEY \ ghcr.io/klavis-ai/linkedin-mcp-server:latest

3.2 无 OAuth 模式（自带令牌）

直接以 JSON 字符串注入 LinkedIn 访问令牌：

# 不带 OAuth 支持 docker run -p 5000:5000 -e AUTH_DATA='{"access_token":"your_linkedin_access_token_here"}' \ ghcr.io/klavis-ai/linkedin-mcp-server:latest

OAuth 前置条件：LinkedIn 强制要求 OAuth 认证。README 明确建议使用 Klavis 免费 API Key 来自动化 OAuth 流程，避免自行处理 LinkedIn 开发者平台的授权回调。

3.3 配置 MCP 客户端

自托管启动后，在任意 MCP 客户端配置文件中指向本地端点（注意路径尾部的/）：

{ "mcpServers": { "linkedin": { "url": "http://localhost:5000/mcp/" } } }

从源码看，服务器实际暴露了两个端点：SSE 端点http://localhost:5000/sse与 StreamableHTTP 端点http://localhost:5000/mcp（见 server.py 的启动日志），两者可同时工作，属于“双传输”设计。

四、可用的 MCP 工具与源码实现

README 将能力概括为 Profile Management、Post Operations、Connection Management、Company Pages、Analytics 五类（其中连接管理、公司主页、数据分析等由 Klavis 托管系统通过渐进式发现按需开放）。在当前开源仓库中，server.py 的list_tools明确注册了以下四个工具，均带LINKEDIN_PROFILE/LINKEDIN_POST类别标注，便于 MCP 客户端做能力分组：

4.1 linkedin_get_profile_info：读取个人资料

对应实现位于 tools/auth.py。调用时若person_id为空，则请求 LinkedInGET /v2/userinfo，返回字段映射如下：

• id←sub
• firstName←given_name
• lastName←family_name
• name←name
• email←email
• email_verified←email_verified
• locale←locale

注意：传入非空person_id时，源码会直接返回提示——读取其他用户的资料需要 LinkedIn API 的更高权限（elevated permissions），不会静默降级。

4.2 linkedin_create_post：发布帖子

对应 tools/posts.py 中的create_post，核心参数如下：

实现要点（可验证于 posts.py）：

• 先请求/userinfo拿到sub作为 person_id，再以urn:li:person:{person_id}作为author组装 UGC Payload；
• 请求体符合 LinkedIn UGC API 规范：lifecycleState: "PUBLISHED"、shareMediaCategory: "NONE"，visibility使用com.linkedin.ugc.MemberNetworkVisibility枚举；
• 话题标签会按#去重补全后拼接在正文末尾；_format_hashtags会先strip()并去掉已存在的#前缀，避免双#；
• 返回结果包含id、created、lastModified、lifecycleState，附带hashtags_used与hashtag_count；
• 失败时给出明确提示：发布需要 LinkedIn App 的w_member_socialscope，且文章式发布失败会自动降级尝试普通文本帖子。

4.3 linkedin_create_url_share：分享链接卡片

与发帖类似，但shareMediaCategory为ARTICLE，并携带media数组（status: "READY"、originalUrl、title、description），从而在 LinkedIn 上生成带预览卡片的链接分享（见 posts.py）。必填参数为url与text，title、description、visibility可选；成功后返回shared_url、url_title、url_description等字段。

4.4 linkedin_format_rich_post：离线富文本格式化

这是一个不发起任何网络请求的纯工具函数，返回 JSON 结构而非直接发布（posts.py）。支持：

• bold_text/italic_text：对正文中匹配的短语分别用**与*包裹（LinkedIn 的 Markdown 风格富文本）；
• bullet_points：以•前缀追加列表；
• numbered_list：以1.2.递增编号追加列表；
• mentions：自动补@追加提及；
• hashtags：自动补#追加话题标签。

返回结果含original_text、formatted_text、各格式化项计数、character_count，并附提示“请用linkedin_create_post发布”，适合 Agent 先排版、后发布的编排模式。

五、底层调用链与鉴权机制

5.1 令牌的三种来源与优先级

server.py 的extract_access_token按以下优先级解析令牌：

1. 环境变量AUTH_DATA（JSON 字符串，取其中access_token字段）——即无 OAuth 模式；
2. 请求头x-auth-data（base64 编码的 JSON，SSE 请求对象与 StreamableHTTP scope 两种形态均被兼容处理）；
3. 兜底环境变量LINKEDIN_ACCESS_TOKEN（源码注释标注“for local use”，本地开发用）。

令牌解析成功后，会通过linkedin_token_context（ContextVar，定义于 tools/base.py）设置到请求级上下文，请求结束后reset清理，从而保证多请求并发时令牌隔离、互不串扰。若上下文与环境变量都拿不到令牌，get_linkedin_access_token会抛出RuntimeError。

5.2 请求封装与 API 常量

tools/base.py 是所有 LinkedIn API 调用的统一出口：

• API 基地址常量LINKEDIN_API_BASE = "https://api.linkedin.com/v2"；
• 请求头固定携带Authorization: Bearer {token}、Content-Type: application/json以及X-Restli-Protocol-Version: 2.0.0（LinkedIn RESTLi 协议版本）；
• 基于aiohttp异步客户端，显式创建默认 SSL 上下文；
• 支持expect_empty_response参数（对 200/201/204 返回None），并对非 JSON 响应做降级包装；
• 错误处理会将aiohttp.ClientResponseError包装为带状态码与响应体的RuntimeError，便于上层工具透出可读错误。

5.3 双传输协议与启动参数

server.py 使用 Starlette 构建 ASGI 应用，同时挂载三组路由：

• GET /sse+Mount /messages/：SSE（Server-Sent Events）传输；
• Mount /mcp：StreamableHTTP 传输，基于StreamableHTTPSessionManager，默认stateless=True无状态模式，可通过--json-response切换为纯 JSON 响应而非 SSE 流。

命令行参数一览（click 定义）：

启动时若当前目录存在.env文件，load_dotenv()会自动加载；直接运行python server.py即可启动服务。

六、依赖与镜像构建

requirements.txt 列出运行所需依赖：mcp==1.11.0、fastapi、uvicorn[standard]、click>=8.0.0、pydantic>=2.5.0、aiohttp>=3.8.0、httpx>=0.27.0、python-dotenv>=1.0.0、typing-extensions、starlette>=0.49.1。

Dockerfile 基于python:3.12-slim，安装gcc编译依赖后拷贝requirements.txt、server.py与tools/目录，以python server.py作为启动命令。开发者也可以克隆仓库后在mcp_servers/linkedin目录下自行docker build，或直接pip install -r requirements.txt后本地运行。

七、权限、限制与排查要点

• OAuth 是硬前提：LinkedIn 不允许匿名调用 UGC API，README 与源码（posts.py 的错误提示）都指出发布类操作需要w_member_socialscope；
• 只读资料走/userinfo：获取当前用户资料使用 OpenID Connect 风格的userinfo端点，字段命名与/v2/people不同（sub/given_name等），使用时可注意字段差异；
• 他人资料需要更高权限：get_profile_info传入person_id会明确拒绝而非尝试；
• 可见性枚举：visibility支持PUBLIC、CONNECTIONS、LOGGED_IN_USERS，映射到com.linkedin.ugc.MemberNetworkVisibility；
• 两种部署形态：托管服务零运维但令牌由 Klavis 托管，Docker 自托管数据可控但需自行处理 OAuth 或注入令牌，可按生产要求取舍。

八、参与贡献与许可

本项目欢迎社区贡献，贡献规范见仓库根目录 CONTRIBUTING.md，代码以 Apache 2.0 协议开源，许可全文见 LICENSE。若需扩展 LinkedIn 能力（如公司主页、数据分析），可在 Klavis 托管系统中通过渐进式发现按需启用，或在仓库中基于 tools/posts.py 与 tools/base.py 的调用模式扩展新的工具实现。

【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis