Wincher Mcp

Wincher MCP

AI コーディングエージェント向けの読み取り専用 Wincher SEO データです。
Cursor、Claude Code、または任意の MCP クライアントをトラッキング対象のウェブサイトに接続して、エディターを離れることなく、キーワード順位、競合他社、SERP、グループを確認できます。

• 設計上、読み取り専用 — Wincher API の GET 形式の利用のみで、アカウントへの書き込みはありません
• Stdio MCP — クライアントによって起動されるローカルプロセスで、HTTP リスナーはありません
• 目的を絞った 9 つのツール — ウェブサイト、キーワード、順位、競合他社、SERP、グループ、一括履歴、注釈
• 堅牢なデフォルト設定 — 入力制限、レスポンス上限、安全なエラー処理、オプションのステージングホスト検証
• TOON 出力に対応 — コンパクトな Token-Oriented Object Notation レスポンスにより、大量のキーワードや順位リストでの LLM トークン使用量を削減できます

Wincher MCP サーバーの正式なオープンソース版です。PyPI パッケージ wincher-mcp、エージェント向けドキュメント、CI、同梱の OpenAPI、オプションの TOON 出力、セキュリティ強化を備えています。初期プロトタイプ chris-tutt/wincher-mcp-server の系譜を引き継いでおり、新たな開発を継続するためのメンテナンス対象リポジトリです。

---

目次

• 利用する理由
• 機能
• クイックスタート
• 要件
• インストール
• 認証
• MCP クライアントの接続
• ツールリファレンス
• エージェント向けプロンプト例
• セキュリティ
• API リファレンス
• トラブルシューティング
• 開発
• 系譜とライセンス

---

利用する理由

Wincher には、SEO ワークフローで必要となるキーワードや競合他社のデータが蓄積されています。このサーバーは、Model Context Protocol を通じてそのデータを公開するため、エージェントは CSV をエクスポートしたりダッシュボードを操作したりせずに、チャットで質問に答えられます。

次のような場合にご利用ください。

• エージェントのセッション内でウェブサイトやキーワードの一覧を確認する
• 対象の検索クエリについて、競合他社や SERP の情報を把握する
• 小規模で監査しやすいツール群を利用する（読み取り専用ツール 9 個）

---

機能

機能	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 レスポンス本文は漏えいしません。

---

クイックスタート

エージェントによるインストールプロンプト

Cursor、Claude Code、または Copilot に貼り付けて、エージェントにお使いのマシンでセットアップを実行するよう依頼してください。

前提条件（変更を加える前に確認してください）：

前提条件	重要な理由
Python 3.10+	wincher_mcp_server.py の実行に必要です
Wincher アカウント	Wincher の設定から取得する個人用アクセストークンが必要です
Stdio MCP	設定では command と args を使用します。HTTP トランスポートは使用しません
絶対パス	MCP 設定で、実在する .venv/bin/python と wincher_mcp_server.py を指定する必要があります
シークレットをリポジトリ外に保存	WINCHER_API_KEY は MCP の env または ~/.zsh_secrets に設定し、決してコミットしないでください

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 パスで引き続き動作します。

仮想環境の名前

CI と同じ .venv を使うか、MCP ホストには pipx を使用してください。それに応じて MCP 設定の command を更新してください。

---

認証

サーバーはトークンをディスクに保存しません。プロセスの環境変数から WINCHER_API_KEY を読み込みます（MCP の env で設定するか、シェルでエクスポートしてください）。

項目	用途
Personal Access Token	https://api.wincher.com（本番環境）へのベアラー認証
ステージング（任意）	MCP 引数 "--use-staging" と、マシン上でのみ設定する環境変数 WINCHER_STAGING_API_HOST

本番 API ホストはサーバー内にハードコードされています。ステージングホストは、このリポジトリに決してコミットしないでください。

ステージング URL は Wincher チームから入手し、非公開の MCP 設定にのみ指定してください。docs/MCP_CONFIG.example.json を参照してください（例の wincher-staging にはホストが設定されていません）。

TOON レスポンス（トークン使用量を削減、任意）

TOON は、LLM に送信する構造化データのコンパクトなエンコード形式です。表形式の Wincher ペイロード（キーワード、競合他社、一括履歴）では、デフォルトの人間が読みやすいテキスト形式と比べて、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 を設定しない場合、デフォルトは人間が読みやすいテキスト形式です。

ラッパーパターン（任意）： シェルスクリプトで source ~/.zsh_secrets を実行してから exec .venv/bin/python wincher_mcp_server.py を実行すると、Dock から起動した Cursor にもキーが渡されます。シークレットを含むスクリプトはコミットしないでください。

ローカルシェルでの使用に限り、.env.example を .env にコピーしてください。.env は gitignore の対象です。

---

MCP クライアントを接続する

クライアント	設定ファイルの場所	設定キー
Cursor	~/.cursor/mcp.json or project .cursor/mcp.json	mcpServers
Claude Code	~/.claude.json or project .mcp.json	mcpServers
VS Code Copilot	.vscode/mcp.json	servers (stdio)

Claude デスクトップアプリ（使用している場合）は、macOS/Windows で同じ mcpServers 形式の claude_desktop_config.json を使用します。詳しくは docs/SETUP.md を参照してください。

すべての例で stdio を使用します。クライアントが Python を起動し、stdin/stdout 経由で JSON-RPC をやり取りします。ログとエラーは stderr に出力されます。

プロジェクトレベルの MCP： リポジトリによっては、command が ローカルラッパー を指す .cursor/mcp.json をコミットしています（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 docs を参照してください。

---

エージェント向けプロンプトの例

• 「Wincher アカウントのすべてのウェブサイトを一覧表示してください。」
• 「ウェブサイト ID 12345 について、トップ 10 のキーワードを表示してください。」
• 「このサイトで、当社と競合 X のランキングを比較してください。」
• 「キーワード ID 67890 の SERP を表示してください。」
• 「平均掲載順位が最も高いキーワードグループはどれですか？」

---

セキュリティ

このサーバーは、お客様の Wincher アカウントに お客様の API トークンを使用して接続します。外部への 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. 完全な監査結果と残存リスク（ステージング環境の設定ミスによる SSRF を含む）について、security_best_practices_report.md を 確認してください。

脅威モデル（概要）

モード	ツールを呼び出せる主体
stdio	Python プロセスを起動した MCP クライアント（ご利用の IDE／エージェントホスト）

---

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／キーワード 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

エージェント：まず 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 を実行してください。