Social Champ

Social Champ MCP 服务

一个面向 Social Champ 平台的模型上下文协议（MCP）服务。它向 Claude Desktop、Claude Code 和 Cursor 等兼容 MCP 的 AI 客户端提供完整的 Social Champ 工具目录：安排和管理帖子、管理已连接的频道和工作区、标签、队列、回收、可分享的日历、代理机构审批工作流，以及 AI 内容向导。

工具

此服务与 Social Champ 实时 MCP 工具目录保持一致。频道是已连接的社交资料；工作区用于归类频道和可分享的日历。工具定义由 tools.schema.json 生成，该文件是实时服务目录的快照，因此工具全集、参数名称和描述均与托管服务保持一致。

工具按领域分组：

• 帖子：创建、更新、删除、批量安排、浏览、重新排序队列、设置 Instagram 首条评论。
• 频道：列出、筛选、获取单个频道、按位置搜索。
• 工作区：列出。
• 日历：查看选项、应用内 URL、创建可分享的日历、列出、更新、删除。
• 队列：暂停、恢复、清空。
• 标签：列出、创建、应用、移除、批量应用。
• 回收：列出集合、回收帖子。
• 代理机构工作流：列出待审批项、批准、拒绝、提醒审批人、批量删除。
• AI 向导：生成帖子、建议话题标签、改写、生成图片。

每个工具都带有 ToolAnnotations 注释，以便客户端应用相应的确认行为。只读工具带有 readOnlyHint=True；破坏性工具（delete_post、delete_shareable_calendar、bulk_delete、queue_clear）带有 destructiveHint=True。代理机构工具还要求调用方令牌带有 manage_team 范围；每个工具的描述中均有说明。

如需查看每个工具所需的参数和范围的完整列表，请参阅此处的 tools.schema.json，或认证仓库中的 api/mcp/IMPLEMENTED.md。

要求

• Python 3.10 或更高版本。
• Social Champ API 密钥或 OAuth2 访问令牌。两者均以 Bearer 令牌形式发送。已发布工具使用的 OAuth2 范围为 read_profile 和 manage_post；代理机构工具（审批、提醒、批量删除）还需要 manage_team。

安装

使用 uv 将其作为 PATH 中的命令：

uv tool install socialchamp-mcp

如果之后你的 shell 找不到 socialchamp-mcp，请运行 uv tool update-shell 并打开新的终端。若要在不安装的情况下运行，请在本 README 提及 socialchamp-mcp 的任何位置使用 uvx socialchamp-mcp。

使用 pip：

pip install socialchamp-mcp

从源代码安装：

git clone https://github.com/socialchamp/socialchamp-mcp.git
cd socialchamp-mcp
pip install -e ".[dev]"

配置

通过环境变量设置配置。

变量	必需	默认值	用途
SOCIALCHAMP_API_KEY	是	无	Bearer 令牌：Social Champ API 密钥或 OAuth2 访问令牌
SOCIALCHAMP_API_BASE_URL	否	https://mcp.socialchamp.com/mcp	覆盖托管 MCP 端点（例如本地测试服务）
SOCIALCHAMP_TIMEOUT	否	30	请求超时时间，单位为秒
SOCIALCHAMP_TRANSPORT	否	stdio	stdio、sse 或 streamable-http
SOCIALCHAMP_MCP_PROTOCOL_VERSION	否	2025-06-18	初始化时发送的 MCP 协议版本

服务仅读取环境变量；它本身不会加载 .env 文件。若要在本地使用，请将变量放入 .env 文件中（在源代码检出目录中，复制 .env.example；否则创建该文件，并在编辑器中写入一行 SOCIALCHAMP_API_KEY=...），确保只有你自己可以读取该文件，并在启动服务之前将其加载到 shell 中：

chmod 600 .env
set -a; . ./.env; set +a

完成后运行 unset SOCIALCHAMP_API_KEY。切勿提交 .env。

MCP 客户端设置

Claude Desktop

将服务添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "socialchamp": {
      "command": "socialchamp-mcp",
      "env": {
        "SOCIALCHAMP_API_KEY": "your-api-key"
      }
    }
  }
}

如果控制台脚本不在 PATH 中，请使用 "command": "python" 和 "args": ["-m", "socialchamp_mcp"]。

Claude Code

最简单的方式是使用托管服务，无需 API 密钥：只需在浏览器中登录 Social Champ。

claude mcp add --scope user --transport http SocialChamp https://mcp.socialchamp.com/mcp

然后在 Claude Code 中运行 /mcp，选择 SocialChamp 并登录。--scope user 会让 MCP 服务在你打开 Claude Code 的每个文件夹中都可用；不加此参数时， 则只在运行命令的文件夹中可用。登录后会授予 read_profile 和 manage_post 权限；审批和其他机构工具需要 manage_team，因此如有需要，请使用 具备该权限的 API 密钥。

若要改为使用 API 密钥在本地运行此软件包，请在不显示密钥、也不将其保存到 Shell 历史记录的情况下读取密钥：

printf 'Social Champ API key: '; read -rs SOCIALCHAMP_API_KEY; printf '\n'
claude mcp add --scope user SocialChamp --env SOCIALCHAMP_API_KEY="$SOCIALCHAMP_API_KEY" -- socialchamp-mcp
unset SOCIALCHAMP_API_KEY

使用 uvx 时，将第二行改为以 -- uvx socialchamp-mcp 结尾即可。与其他 服务的环境变量一样，Claude Code 会将密钥保存在自身设置中（~/.claude.json）， 并且在命令运行期间，机器上的其他进程也能看到该密钥。在共享机器上，建议优先使用托管登录。

Claude Code 日历窗格

在使用 Claude Code？Social Champ 日历扩展 会在此 MCP 服务上添加侧边窗格，提供周、月和日视图、失败的帖子 和审批、草稿，以及使用 Claude 撰写的新帖子。它会先显示每项更改，只有在你按下 Yes 后才会发送。 它还会在 Claude 通过聊天更改 Social Champ 中的任何内容前征求你的同意。

claude plugin marketplace add SocialChamp/socialchamp-claude-mods
claude plugin install socialchamp-calendar@socialchamp-mods

它需要 Claude Code 2.1.293 或更高版本。运行 /reload-plugins，然后运行 /socialchamp-calendar。该扩展会查找名为 SocialChamp 的 MCP 服务，也就是上文添加的名称，因此无需进行设置。如果你使用了其他名称添加服务， 请通过 /plugin configure socialchamp-calendar@socialchamp-mods 设置一次该名称。在自动模式下， 窗格打开后，按照扩展的 README 添加权限规则（mcp__<server name>__<tool>，名称中的空格用下划线替代）。

通过 HTTP 运行

默认传输方式是 stdio，Claude Desktop 和 Claude Code 都使用这种方式。若要改为通过 HTTP 运行，请设置 SOCIALCHAMP_TRANSPORT：

printf 'Social Champ API key: '; read -rs SOCIALCHAMP_API_KEY; printf '\n'
export SOCIALCHAMP_API_KEY
SOCIALCHAMP_TRANSPORT=streamable-http socialchamp-mcp

也支持 sse。将客户端指向生成的 HTTP 端点。

映射到实际 API

这些工具通过 JSON-RPC 转发到托管的 Social Champ MCP 服务。在线工具在身份验证后端（api/mcp/handlers.ts）中实现，并通过外部 API 密钥无法直接调用的内部服务路由访问 champ，因此用户令牌要访问完整目录中的工具，只能通过托管的 MCP 服务。src/socialchamp_mcp/client.py 是唯一发起 HTTP 调用的文件：它使用 SOCIALCHAMP_API_BASE_URL 中的端点进行 JSON-RPC 2.0 通信（initialize、tools/list、 tools/call）。

src/socialchamp_mcp/server.py 是根据 tools.schema.json 生成的，后者是在线服务 api/mcp/tools.ts 的快照。在线工具目录发生变化后，可按以下步骤刷新：

1. 将身份验证代码库中的快照重新导出到 tools.schema.json（在线的 tools.ts 数组，格式为 JSON）。
2. 运行 python scripts/generate_server.py。

Social Champ 的身份验证指南确认了基础 URL 和 Bearer 身份验证。

项目结构

socialchamp-mcp/
├── tools.schema.json        # snapshot of the live tool catalog (source for codegen)
├── scripts/
│   └── generate_server.py   # regenerates server.py from tools.schema.json
├── src/
│   └── socialchamp_mcp/
│       ├── __init__.py
│       ├── __main__.py      # python -m socialchamp_mcp
│       ├── config.py        # settings from the environment
│       ├── client.py        # the only file that makes HTTP calls (JSON-RPC)
│       └── server.py        # GENERATED: FastMCP instance and tool definitions
└── tests/
    └── test_server.py

添加工具

工具通过生成创建，而非手动编写。在身份验证代码库的在线 api/mcp/tools.ts 中添加工具，刷新 tools.schema.json，然后运行 python scripts/generate_server.py。生成器会将每个工具映射到一个转发至 call_tool 的 @mcp.tool 函数，选择一个 ToolAnnotations 预设（READ、WRITE、UPDATE、DESTRUCTIVE），并根据工具描述生成文档字符串。添加具有破坏性或只读属性的工具时，请更新 scripts/generate_server.py 中的分类集合。

完整清单请参阅 CONTRIBUTING.md。

开发

pip install -e ".[dev]"
pytest

如需确认 MCP 服务能否通过 stdio 启动：

SOCIALCHAMP_API_KEY=dummy SOCIALCHAMP_TIMEOUT=5 socialchamp-mcp

它会等待从 stdin 输入内容，而不是直接退出。按 Ctrl+C 停止。

安全性

• API 密钥从环境变量中读取，并作为 Bearer 令牌发送。此服务不会记录该密钥，也不会将其写入磁盘。
• 请将密钥保存在 .env 或客户端的密钥存储中。切勿提交密钥，也不要在命令行中输入，因为 Shell 历史记录会保留它。.gitignore 会排除 .env。使用 OAuth 登录（托管服务）无需密钥。
• 工具会标注为只读、写入或破坏性操作。破坏性工具（delete_post、delete_shareable_calendar、bulk_delete、queue_clear）带有 destructiveHint=True，以便客户端在运行前确认。
• Agency 工具要求调用方的令牌包含 manage_team 作用域。不含该作用域的令牌无法调用这些工具。
• 请将令牌的权限范围限制为工具所需的权限。如果令牌泄露，请在 Social Champ 账户中轮换令牌。

许可证

MIT。请参阅 LICENSE。