Wincher Mcp

Wincher MCP

为 AI 编码 Agent 提供只读的 Wincher SEO 数据。
将 Cursor、Claude Code 或任何 MCP 客户端连接到你跟踪的网站：关键词排名、竞争对手、SERP 和分组，无需离开编辑器。

• 默认只读 — 仅使用 GET 风格的 Wincher API；不会对你的账户进行写入
• Stdio MCP — 由客户端启动的本地进程；不监听 HTTP
• 九种专用工具 — 网站、关键词、排名、竞争对手、SERP、分组、批量历史记录、注释
• 强化的默认设置 — 输入限制、响应上限、安全错误处理、可选的暂存主机验证
• 可选 TOON 输出 — 紧凑的 Token-Oriented Object Notation 响应，减少大型关键词和排名列表对 LLM token 的占用

规范的开源 Wincher MCP 服务：PyPI 软件包 wincher-mcp、Agent 文档、CI、内置 OpenAPI、可选 TOON 输出和安全强化。源自早期的 chris-tutt/wincher-mcp-server 原型；本仓库是后续开发的维护中心。

---

目录

• 为何使用
• 功能
• 快速开始
• 要求
• 安装
• 身份验证
• 连接 MCP 客户端
• 工具参考
• Agent 示例提示词
• 安全性
• API 参考
• 故障排除
• 开发
• 沿革与许可证

---

为何使用

Wincher 保存着 SEO 工作流所依赖的关键词和竞争对手数据。此服务通过 Model Context Protocol 提供这些数据，让 Agent 可以在聊天中回答问题，无需导出 CSV 或逐一点击仪表板。

适用于以下场景：

• 在 Agent 会话中查看网站和关键词列表
• 获取目标查询的竞争对手和 SERP 背景信息
• 使用精简、可审计的工具集（九种只读工具）

---

功能

功能	MCP 工具
列出跟踪的网站	get_websites
关键词和当前排名	get_keywords
历史排名序列	get_keyword_rankings
竞争对手汇总指标	get_competitor_ranking_summaries
各关键词的竞争对手排名	get_competitor_keyword_positions
SERP 快照和特征	get_serps
关键词分组汇总	get_keyword_groups
批量排名历史记录	get_bulk_ranking_history
SEO 注释／备注	get_annotations

输入验证 — 正整数 ID、有上限的批量列表，以及适用时经过验证的日期字符串。

清晰的错误信息 — HTTP 请求失败时会返回端点和状态码，不会泄露完整 URL、令牌或原始 API 响应正文。

---

快速开始

Agentic 安装提示词

粘贴到 Cursor、Claude Code 或 Copilot 中，并让 Agent 在你的机器上运行设置。

假设（更改任何内容前请确认）：

假设	重要原因
Python 3.10+	运行 wincher_mcp_server.py 所需
Wincher 账户	从 Wincher 设置中获取个人访问令牌
Stdio MCP	配置使用 command + args；不使用 HTTP 传输
绝对路径	MCP 配置必须指向实际的 .venv/bin/python 和 wincher_mcp_server.py
密钥不入库	在 MCP env 或 ~/.zsh_secrets 中设置 WINCHER_API_KEY，绝不提交

Set up the wincher-mcp MCP server from https://github.com/vmandic/wincher-mcp on this machine end-to-end.

Before you change anything, confirm with me:
1) Which MCP client I use (Cursor, Claude Code, or VS Code Copilot).
2) Where to clone the repo (default: ~/source/vmandic/wincher-mcp).

Then:

A) Prerequisites — Python 3.10+, no secrets in git.
B) Clone, venv, test — git clone, python3 -m venv .venv, pip install -r requirements.txt -r requirements-dev.txt, pytest -q, py_compile wincher_mcp_server.py.
C) Wincher token — I create a Personal Access Token in Wincher; add WINCHER_API_KEY to MCP env (or ~/.zsh_secrets if using a wrapper script).
D) MCP config — stdio: command = ABSOLUTE_PATH/.venv/bin/python, args = [ABSOLUTE_PATH/wincher_mcp_server.py], env = { WINCHER_API_KEY }. See docs/MCP_CONFIG.example.json. Do not commit real keys or staging hosts.
E) Verify — restart MCP client, call get_websites, report results or auth errors.

Summarize: clone path, config file edited, and exact JSON used.

手动设置

1. 克隆并安装

git clone https://github.com/vmandic/wincher-mcp.git
cd wincher-mcp
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. API 密钥 — Wincher → Settings → Personal Access Tokens。复制令牌后仅存储在环境变量或本地密钥文件中。

3. MCP 客户端 — Cursor 配置示例（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "wincher-mcp": {
      "command": "/absolute/path/to/wincher-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/wincher-mcp/wincher_mcp_server.py"],
      "env": {
        "WINCHER_API_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

生产环境、可选的暂存环境和 TOON 配置项请参阅 docs/MCP_CONFIG.example.json。

4. 重启客户端，然后询问：“列出我的 Wincher 网站”（get_websites）。

完整操作指南：docs/SETUP.md。更多提示词：docs/EXAMPLES.md。

---

要求

要求	备注
Python	3.10 或更高版本（CI 测试 3.10–3.12）
Wincher 账户	需具备 API 访问权限，并有已跟踪的网站/关键词
API 令牌	个人访问令牌；环境变量 WINCHER_API_KEY
MCP 客户端	Cursor、Claude Code 或任何 stdio MCP 宿主

---

安装

从 PyPI 安装（推荐）

pipx install wincher-mcp
# or: pip install wincher-mcp

之后，MCP 配置使用控制台脚本（无需克隆路径）：

{
  "mcpServers": {
    "wincher": {
      "command": "wincher-mcp",
      "args": [],
      "env": { "WINCHER_API_KEY": "YOUR_KEY_HERE" }
    }
  }
}

如需查找二进制文件路径：pipx which wincher-mcp。

软件包：pypi.org/project/wincher-mcp。发布：docs/PYPI.md。

从克隆的仓库安装（开发）

git clone https://github.com/vmandic/wincher-mcp.git
cd wincher-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -q

仓库根目录中的旧启动器 wincher_mcp_server.py 仍可用于现有 MCP JSON 路径。

虚拟环境名称

使用 .venv（与 CI 一致），或在 MCP 宿主中使用 pipx。相应更新 MCP 配置中的 command。

---

身份验证

服务绝不会将令牌存储到磁盘。它会从进程环境中读取 WINCHER_API_KEY（在 MCP env 中设置或在 shell 中导出）。

内容	用途
个人访问令牌	用于 https://api.wincher.com（生产环境）的 Bearer 身份验证
可选的暂存环境	MCP 参数 "--use-staging"，以及仅在你的机器上设置的环境变量 WINCHER_STAGING_API_HOST

生产环境的 API 主机已在服务中硬编码。暂存环境主机绝不能提交到此仓库。

向 Wincher 团队获取暂存环境 URL；仅在私有 MCP 配置中设置。参阅 docs/MCP_CONFIG.example.json（示例中的 wincher-staging 未设置主机）。

可选的 TOON 响应（减少令牌用量）

TOON 是一种用于向大模型发送结构化数据的紧凑编码格式。Wincher 的表格类数据（关键词、竞争对手、批量历史记录）使用 TOON 时，所需令牌通常比默认的易读文本布局减少 30–60%。

模式	方法
服务默认使用 TOON	在 MCP 服务的 args 数组中添加 "--use-toon"（参阅 docs/MCP_CONFIG.example.json 中的 wincher-toon）
单次调用	在任何工具调用中传入 "output_format": "toon"（若启用了 --use-toon，也可传入 "text" 强制使用易读文本）

响应包含简短的前导说明和 TOON 正文。使用 python-toon 在 Python 中解码：

from toon import decode

如果未设置 --use-toon，默认仍为易读的文本格式。

包装器模式（可选）： shell 脚本可以先 source ~/.zsh_secrets，然后 exec .venv/bin/python wincher_mcp_server.py，这样即使从 Dock 打开 Cursor，也能获取密钥。不要提交包含密钥的脚本。

将 .env.example 复制为 .env，仅供本地 shell 使用；.env 已加入 gitignore。

---

连接 MCP 客户端

客户端	配置位置	配置键
Cursor	~/.cursor/mcp.json 或项目 .cursor/mcp.json	mcpServers
Claude Code	~/.claude.json 或项目 .mcp.json	mcpServers
VS Code Copilot	.vscode/mcp.json	servers（stdio）

Claude 桌面应用（如果你使用）在 macOS/Windows 上使用 claude_desktop_config.json，结构与 mcpServers 相同；请参阅 docs/SETUP.md。

所有示例都使用 stdio：客户端会启动 Python，并通过 stdin/stdout 进行 JSON-RPC 通信。日志和错误会写入 stderr。

项目级 MCP： 有些仓库会提交 .cursor/mcp.json，其中的 command 指向本地包装脚本（JSON 中不包含机密信息）。全局用户配置也可以为所有工作区配置同一个服务。

---

工具参考

所有工具均为只读。参数使用 get_websites / get_keywords 返回的 Wincher 网站 ID/关键词 ID。

工具	主要输入
get_websites	—
get_keywords	website_id
get_keyword_rankings	website_id、keyword_id、日期范围
get_competitor_ranking_summaries	website_id
get_competitor_keyword_positions	website_id、竞争对手筛选条件
get_serps	website_id、keyword_id
get_keyword_groups	website_id
get_bulk_ranking_history	website_id、关键词 ID 列表（数量有限制）
get_annotations	website_id

字段级详情：随附的 docs/api/wincher-openapi.json 和 Wincher API 文档。

---

面向 Agent 的提示词示例

• “列出我 Wincher 账户中的所有网站。”
• “对于网站 ID 12345，显示排名前 10 的关键词。”
• “比较此网站上我们的排名与竞争对手 X 的排名。”
• “显示关键词 ID 67890 对应的 SERP。”
• “哪个关键词组的平均排名最好？”

---

安全

此服务使用你的 API 令牌调用你的 Wincher 账户。请像对待任何具有出站 HTTPS 通信能力的本地工具一样对待它。

我们在代码中实施的措施

控制措施	详情
只读工具	不创建/更新/删除 Wincher 资源
仅限 Stdio	服务不监听网络
固定生产主机	源代码中为 https://api.wincher.com
暂存 URL 验证	仅允许 HTTPS；阻止 localhost/私有/元数据主机
不跟随重定向	HTTP 客户端设置 follow_redirects=False
限制输入/输出范围	对 ID 进行验证、限制批量数量、限制格式化响应中的行数
错误信息脱敏	工具错误信息不会包含令牌和完整响应正文

你应该做的事

1. 切勿提交 .env、包含真实密钥的 MCP JSON，或 WINCHER_STAGING_API_HOST 的值。
2. 如果 .cursor/mcp.json 可能包含与机密信息工作流相关的本地路径，请优先将其加入项目的 gitignore。
3. 请查看 security_best_practices_report.md，了解完整审计结果和剩余风险（包括暂存环境配置错误时的 SSRF 风险）。

威胁模型（简要）

模式	谁可以调用工具？
stdio	启动 Python 进程的 MCP 客户端（你的 IDE / Agent 宿主）

---

API 参考

OpenAPI 文件随附自 wincher.com/docs/api：

文件	用途
docs/api/wincher-openapi.json	规范快照
docs/api/META.json	fetched_at、source_chunk_sha256
docs/api/README.md	刷新说明

在本地刷新：

python3 scripts/fetch_wincher_openapi.py

CI 每周会根据 META.json 运行一次漂移检查（scripts/fetch_wincher_openapi.py --check）。

---

故障排除

症状	尝试方法
未列出 MCP 服务	重启客户端；检查 .venv/bin/python 和 wincher_mcp_server.py 的绝对路径。
未设置 WINCHER_API_KEY	将令牌添加到 MCP env，或添加到用于加载密钥文件的包装器中。
HTTP 401	在 Wincher 中重新生成令牌；更新环境变量；重启客户端。
数据为空或不完整	确认 Wincher UI 中存在网站/关键词；检查网站/关键词 ID。
暂存环境错误	确保在 args 中设置 --use-staging，并在 env 中设置 WINCHER_STAGING_API_HOST（仓库中不包含此主机）。

手动测试 API 密钥：

curl -sS -H "Authorization: Bearer YOUR_KEY" https://api.wincher.com/v1/websites

---

开发

每次推送到 main 以及每个拉取请求都会运行 CI：

作业	执行内容
test	Python 3.10 / 3.11 / 3.12 — pip install、py_compile、pytest、pip-audit
api-spec-check	每周（以及按计划）— 验证 Wincher 文档分块哈希与 docs/api/META.json 是否一致

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt
pytest -q
pip-audit -r requirements.txt -r requirements-dev.txt
python3 scripts/fetch_wincher_openapi.py          # refresh spec
python3 scripts/fetch_wincher_openapi.py --check  # drift check

目录结构：

wincher_mcp_server.py   # MCP entry (stdio)
scripts/                # OpenAPI fetch
docs/api/               # Vendored spec + META
test/                   # pytest (security, fetch script)
.cursor/                # Agent rules and skills
AGENTS.md               # Pointer for coding agents

Agent：从 AGENTS.md 和 .cursor/rules/ 开始。

Dependabot：.github/dependabot.yml（pip + GitHub Actions）。

---

源流与许可证

项目	链接
仓库	github.com/vmandic/wincher-mcp
PyPI	pypi.org/project/wincher-mcp
早期原型	github.com/chris-tutt/wincher-mcp-server
Wincher API	wincher.com/docs/api
MCP SDK	modelcontextprotocol/python-sdk

MIT — 由 Vedran Mandić 和贡献者维护。

欢迎通过议题和拉取请求贡献。在提交 PR 前运行 pytest 和 pip-audit。