Markaestro

@markaestro/mcp

一个 Model Context Protocol 服务，可让 AI Agent（Claude Code、Claude、Cursor、ChatGPT、Grok、Grok Bot、OpenClaw、Hermes 以及其他任何 MCP 客户端）通过公共 API 安排、发布和审核 Markaestro 帖子。各客户端的具体连接步骤见 https://markaestro.com/developers/agents（`?client=cursor`、`chatgpt`、`grok`、 grok-bot、openclaw、hermes 或 headless 可打开对应选项卡）。

每个密钥可覆盖一个品牌，也可覆盖其工作区中的所有品牌；在创建密钥或登录授权时选择。单品牌密钥仅适用于该品牌。全品牌密钥可查看所有品牌：list_products 会返回所有品牌，Agent 会向 create_post、create_posts、list_posts 和 create_evergreen_queue 以及分析工具传入 productId，以便针对单个品牌而非整个工作区进行报告。

工具

工具	功能
list_products	此密钥可操作的品牌（工作区中的一个或全部）及其已连接的渠道
list_destinations	品牌可发布的目标位置（主页、账号）及其 ID
get_brand_profile	品牌的描述、语气和视觉形象（只读）
list_posts, get_post	按状态读取帖子，并使用 cursor 翻页
create_post	保存草稿；设置 scheduledAt 时则安排发布
update_post	编辑草稿或已安排的帖子：文案、媒体、某个渠道的设置或发布时间
publish_post	将帖子加入队列并立即发布；返回一次任务运行记录
mark_post_posted	记录用户已发布手动提醒或 TikTok 收件箱中的帖子
delete_post	删除草稿，或在帖子发布到任何平台之前取消；拒绝删除已发布的帖子
bulk_posts	重新安排最多 25 个帖子的发布时间或状态
create_posts	一次调用最多创建 25 个帖子，并返回每项结果
upload_media	从文件路径、URL 或数据 URL 上传；返回资源 ID
list_media, get_media	查看已上传的资源、处理状态和引用计数
get_analytics	指定时间段内的品牌表现：总计、渠道、每日序列、热门帖子、热图和洞察。涵盖通过 Markaestro 发布的帖子，以及直接在平台上发布的帖子
list_post_analytics	列出时间段内的所有帖子及其最新指标和来源，并可按观看量、覆盖人数、互动量或互动率排序
get_post_analytics_history	查看单个帖子的 1h 至 90d 指标快照，以及各阶段间的增长情况
refresh_analytics	立即从平台拉取实时指标（每分钟可调用几次）
suggest_post_times	根据品牌自身的历史数据，推荐最佳发布时间段
get_job_run, list_job_runs	跟踪发布任务直至成功或失败
get_channel_rules	各渠道的媒体、文案和投递模式规则
get_tiktok_posting_options	TikTok 创作者当前的隐私级别和互动选项，直接发布时需要这些信息

Evergreen 工具（preview_、create_、get_、list_、update_、 activate_、pause_ 和 resume_evergreen_queue、list_evergreen_runs、 get_evergreen_analytics）用于管理经过验证的周期性内容。

Agent 仅管理社交媒体，不涉及其他事务：不开放账号设置、账单、 团队、API 密钥、webhook 和渠道连接，也没有工具可以删除已发布的帖子、 将帖子从平台下架或归档 Evergreen 队列。这些操作由用户在 Markaestro 中完成。 通过 Agent 登录签发的密钥在 REST 层也遵循相同规则：它 无法删除已发布的帖子、将帖子从平台下架或管理 webhook （FORBIDDEN_AGENT_CONNECTION）。用户在 Settings 中创建的密钥 则保留其作用域所允许的完整 REST 接口。

此外还提供 markaestro://channel-rules 资源，以及一个 schedule_post 提示词，引导 Agent 安全地安排发布。

发布流程以草稿为先。不带 scheduledAt 的 create_post 绝不会发布； publish_post 是唯一可以立即发布的工具，其说明要求 Agent 先征得用户确认。

两种连接方式

托管版（无需安装，无需粘贴）。 Markaestro 通过 Streamable HTTP 在 https://markaestro.com/api/public/v1/mcp 提供相同的工具。无需凭据即可添加，首次调用工具时会打开浏览器：登录，选择工作区和品牌，然后点击 Allow。客户端会收到绑定到该品牌的 API key，并自动刷新。

claude mcp add --transport http markaestro https://markaestro.com/api/public/v1/mcp

这是标准的 OAuth 2.1（PKCE、动态客户端注册，以及在 /.well-known/oauth-protected-resource 和 /.well-known/oauth-authorization-server 上的发现机制），因此 claude.ai、Cursor 和其他 MCP 客户端都可以通过相同方式连接。已连接的 Agent 会列在 Settings、API 中，也可在此撤销。

对于无头环境或 CI，可改为通过 bearer 标头传递工作区 API key：

claude mcp add --transport http markaestro https://markaestro.com/api/public/v1/mcp \
  --header "Authorization: Bearer mk_live_..."

{
  "mcpServers": {
    "markaestro": {
      "type": "http",
      "url": "https://markaestro.com/api/public/v1/mcp",
      "headers": { "Authorization": "Bearer mk_live_..." }
    }
  }
}

添加额外标头 x-markaestro-read-only: 1，即可仅获取读取工具。

本地包。 通过 stdio 在本机运行服务，这也能让 upload_media 读取本地文件：

设置

1. 在 Markaestro 的 Settings > API Access 下创建 API key。选择品牌、Agent 所需的作用域（products.read、posts.read、posts.write、media.write，以及可能发布内容时所需的 posts.publish），并建议在评估期间使用测试 key。
2. 通过 MARKAESTRO_API_KEY 将 key 提供给服务。

Claude Code

claude mcp add markaestro -e MARKAESTRO_API_KEY=mk_live_... -- npx -y @markaestro/mcp

Claude Desktop、Cursor 和其他 JSON 配置

{
  "mcpServers": {
    "markaestro": {
      "command": "npx",
      "args": ["-y", "@markaestro/mcp"],
      "env": { "MARKAESTRO_API_KEY": "mk_live_..." }
    }
  }
}

环境变量

变量	必需	默认值
MARKAESTRO_API_KEY	是	n/a
MARKAESTRO_BASE_URL	否	https://markaestro.com
MARKAESTRO_READ_ONLY	否	未设置；1 表示仅注册读取工具

服务为你完成的工作

• 每次修改操作都会发送一个 Idempotency-Key，每次调用生成一次，因此重试请求会重放，而不是重复发布。
• 根据服务端的 Retry-After 重试 429 和暂时性 5xx 响应。
• 执行三步直接媒体上传（会话、向存储发送 PUT、完成），且绝不会将 API key 发送到存储 URL。
• 将 API 故障作为工具错误返回，其中包含稳定的错误 code、各渠道的 issues（如有），以及关于如何修改的提示。

Claude Code 插件

此技能和托管服务会作为一个插件一同发布：

claude plugin marketplace add markaestro/markaestro-agents
claude plugin install markaestro@markaestro

部署

维护者：完整的发布操作手册（涵盖所有发布对象、版本文件和确切命令）位于 Markaestro 应用仓库的 docs/operations/mcp-release.md。摘要：

发布对象	发布方式
托管 MCP（/api/public/v1/mcp）	属于 Next.js 应用的一部分；像其他路由一样，在推送到 main 时部署
npm 上的 @markaestro/mcp	cd mcp && npm version <x.y.z> && npm publish（公开的带作用域包；prepublishOnly 会进行构建）。同时更新 src/version.ts
插件和技能	使用 node scripts/sync-agents-repo.mjs <clone> 镜像到公开仓库 markaestro/markaestro-agents，然后推送到该仓库；运行 claude plugin marketplace add markaestro/markaestro-agents 即可读取。技能也可以单独复制到 ~/.claude/skills/markaestro
MCP Registry（com.markaestro/mcp）	同一版本发布到 npm 后：运行 mcp-publisher login http --domain markaestro.com --private-key <hex>，然后在 mcp/ 中运行 mcp-publisher publish。公钥通过 /.well-known/mcp-registry-auth 提供
Glama（markaestro/markaestro-agents）	Admin，Dockerfile：构建步骤 npm install -g @markaestro/mcp@<version>，CMD markaestro-mcp；执行 Build，然后 Create Release

开发

cd mcp
npm install
npm run build
MARKAESTRO_API_KEY=mk_test_... MARKAESTRO_BASE_URL=http://localhost:3000 npm run smoke            # local stdio
MARKAESTRO_API_KEY=mk_test_... MARKAESTRO_BASE_URL=http://localhost:3000 npm run smoke -- --remote # hosted endpoint

单元测试位于 src/__tests__，使用仓库的 npm test 运行。冒烟脚本会通过 stdio 启动构建后的服务、列出工具、读取品牌信息、创建草稿、重新读取草稿，然后将其删除。不会发布任何内容。