tvpulse-mcp

TVPulse カスタマーAPI（日本のテレビCM/露出分析SaaS）を Claude Code などの MCP クライアントから ローカル（stdio）で使うための MCP サーバーです。

これは何か

/v1/api/searches（検索定義＋投影）を土台に、1回の課金付き検索作成のあとに無料の集計・証跡取得を 組み合わせた12個のツールを公開します。生のOCR/ASR検索を都度課金する方式ではなく、1つの質問に対して 1回の検索を作成し、トレンド・内訳・番組・証跡をまとめて返します。支出はすべて人の承認を経てから実行 されます（下記「承認フローと予算」）。

インストール

3つの方法があります。迷ったら Claude Codeプラグイン（設定不要でAPIキーを安全に保存）を おすすめします。

方法1: Claude Codeプラグイン（推奨）

/plugin marketplace add https://tvpulse.io/claude/marketplace.json
/plugin install tvpulse@tvpulse

Claude Code バージョン 2.1.224 以降が必要です。インストール時にAPIキーの入力を求められます （安全に保存され、チャット欄には表示されません）。承認しきい値・セッション予算はデフォルト値 （20クレジット / 200クレジット）のままで構いません。監視スキルも同時にインストールされます。 詳細は distribution/claude-plugin/README.md を 参照してください。

前提条件: uv がインストールされていること（uvx を使用します）。

方法2: Claude Desktop拡張機能（.mcpbバンドル）

https://tvpulse.io/claude/tvpulse.mcpb から tvpulse.mcpb をダウンロードし、ダブルクリックするか Claude Desktop の 「設定 > 拡張機能 > ローカルにインストール」から追加してください。初回起動時にAPIキーの入力を 求められます。前提条件は方法1と同じく uv/uvx です。

方法3: 手動セットアップ（Claude Code、バージョン固定インストール）

uvx tvpulse-mcp==1.1.0

Claude Code に直接登録する場合:

claude mcp add tvpulse \
  -e TVPULSE_API_KEY=your-api-key \
  -e TVPULSE_CONFIRM_ABOVE_CREDITS=20 \
  -e TVPULSE_SESSION_BUDGET_CREDITS=200 \
  -- uvx tvpulse-mcp==1.1.0

APIキーは環境変数で渡してください（チャット欄に貼り付けないでください）。開発環境（dev gateway）に 向ける場合は TVPULSE_BASE_URL を追加します:

claude mcp add tvpulse \
  -e TVPULSE_API_KEY=your-dev-api-key \
  -e TVPULSE_BASE_URL=https://gateway.dev.tvpulse.io \
  -e TVPULSE_CONFIRM_ABOVE_CREDITS=20 \
  -e TVPULSE_SESSION_BUDGET_CREDITS=200 \
  -- uvx tvpulse-mcp==1.1.0

TVPULSE_BASE_URL を省略した場合は本番 https://gateway.tvpulse.io を使います (tvpulse.client.DEFAULT_BASE_URL と同じ値)。

フレーム表示リンク (view_url) の宛先は TVPULSE_WEB_BASE_URL で決まります。既定は本番 https://tvpulse.io で、開発環境では -e TVPULSE_WEB_BASE_URL=https://dev.tvpulse.io を追加します。

APIキーをまだお持ちでない場合

いずれの方法でも、APIキー未設定のまま tvpulse_check_connection などのツールを呼び出すと、 発行手順（https://tvpulse.io/account/api-keys ）と、お使いのクライアント別の設定方法を案内する 日本語メッセージが返ります。

登録後、最初にこう聞いて接続を確認してください:

TVPulseに接続できているか確認して

これは無料の tvpulse_check_connection を呼び出し、APIキーの有効性・接続先・残高・設定済み予算を 表示します。

承認フローと予算

tvpulse_search_mentions と課金付き tvpulse_export_records_create は次の順で承認を経ます:

1. まず見積もり（無料）を取り、interpretation（キーワード/モード、日本語の局名と地域、明示的な JST期間、CMポリシー）を必ず提示します。
2. ホスト版は正のクレジットを使うすべての呼び出しで needs_confirmation と confirm_token を返します。 ローカル stdio 版は TVPULSE_CONFIRM_ABOVE_CREDITS（既定20クレジット）以下をそのまま実行します。
3. stdio 版でしきい値を超えた場合は MCP elicitation で直接確認します。対応していないクライアントには needs_confirmation と confirm_token（10分間有効、1回限り）を返します。見積もりをユーザーに提示し、 承認された場合のみ同じツールを confirm_token とともに再実行してください。
4. TVPULSE_SESSION_BUDGET_CREDITS（既定200クレジット、このセッション累計の上限）を超える場合は、 何を渡しても上書きできない拒否になります。より多く使いたい場合は、より大きな値でセッションを 再起動してください。
5. outcome=enterprise_review は予算の問題ではなく個別見積もりが必要な料金区分です。クレジットを 増やしても解決しません。

トレンドレポート一覧と料金確認は無料です。詳細の初回正常取得は組織ごと・レポートIDごとに5クレジットで、 同じ組織による同じIDの再取得や編集後の取得は無料です。詳細を取得する前に料金を提示し、設定済みの自動承認しきい値に かかわらず、利用者の明示的な承認を得てください。エクスポートのステータス確認も無料です。

重要: ホスト版の承認しきい値は0に固定です。stdio版のしきい値とセッション予算は環境変数で設定でき、 ツール引数では上げられません。confirm_token の再送だけでは人間による承認を証明できないため、 クライアントは必ずユーザーの明示的な承認後に再実行してください。

ホスト版の利用状況ログ（クライアント別）

ホスト版（Streamable HTTP）の各ツール呼び出しは、tvpulse_mcp.hosted.usageロガーから mcp_hosted_tool_callイベント（event/ts/tool/client/org_id/status、必要ならerror_code。 ユーザーID相当の識別子・ベアラートークン・OAuth client ID・User-Agent・ツール引数は含まない）としてJSON1行で記録されます （src/tvpulse_mcp/hosted/usage_logging.py）。tsはタイムゾーン付きのUTC ISO-8601（例: 2026-09-26T03:04:05.123Z）で、ログ収集側のフォーマッタやポッドのタイムゾーンに関わらず一意に 日時を復元できます。この既存ログから「クライアント別の週次アクティブ組織数」と、二回目のセッション復帰を 示す代理指標として「初回観測から24〜336時間後の遅延再呼び出し率」を集計するスクリプトを用意しています。 成功・失敗のどちらの呼び出しも試行として数えます。週次コホートは、その週の全組織が初回観測から336時間 経過するまでpendingになり、1組織でも未成熟なら週全体の分子・分母・率を出しません。入力ログは測定開始点から 明示した観測カットオフまで完全である必要があります。不完全なログでは初回観測も成熟度も確定できません:

uv run python scripts/usage_metrics.py path/to/hosted.log \
  --observation-cutoff 2026-10-10T00:00:00Z

--observation-cutoffは必須のUTC日時（Zまたは+00:00付き）です。カットオフより後のイベントは無視されます。 このカットオフで週次コホート全体が未成熟なら、出力の分子・分母・率はnullのままです。保持期間が限られる kubectl logs --sinceのようなrolling windowだけでは、測定開始点からの完全な履歴を保証できないため、判定用入力に 使わないでください。

このレポートにシークレットは不要です。識別子にはorg_idのみを使います。 旧ログのuser_id_hashフィールドは無視します。

スクリプトは各ログ行のtsフィールド（UTC ISO-8601）を優先して読みます。tsを含まない古い記録は _ts/timestamp/asctimeにフォールバックしますが、これらはタイムゾーンなし（naive）の場合が あり、その場合は--naive-tzで指定したゾーン（既定はAsia/Tokyo。ホストポッドのTZと一致）で 解釈します。UTCだと決め打ちすることは絶対にありません。日時が一切含まれていない行は集計対象外に なります。

ツール一覧

ツール	課金	ゲートウェイルート
tvpulse_check_connection	無料	GET /v1/api/credits（キー検証を兼ねる）
tvpulse_list_channels	無料	なし（静的カタログ）
tvpulse_estimate	無料	POST /v1/api/credits/estimate
tvpulse_search_mentions	課金あり（承認フロー経由）	POST /v1/api/searches + GET .../trend,breakdown,programs,evidence
tvpulse_get_evidence	無料	GET /v1/api/searches/{id}/evidence
tvpulse_get_search_results	無料	GET /v1/api/searches/{id}/{trend,breakdown,programs,evidence}（再取得）
tvpulse_get_hit_context	無料	GET /v1/api/searches/{id}/context?around_hits=true
tvpulse_save_evidence_csv	無料（ローカルファイル書き込み）	GET /v1/api/searches/{id}/evidence（ページング）
tvpulse_credits_balance	無料	GET /v1/api/credits
tvpulse_export_records_create	dry_run=falseで課金（承認フロー経由）	POST /v1alpha1/exports
tvpulse_export_records_status	無料	GET /v1alpha1/exports/{export_id}
tvpulse_trend_reports_list	無料	GET /v1alpha1/trend-watch/catalog/reports
tvpulse_trend_reports_quote	無料	GET /v1alpha1/trend-watch/catalog/reports/{id}/quote
tvpulse_trend_reports_get	初回の正常取得は組織・レポートIDごとに5クレジット。同じIDの再取得や編集後の取得は無料。明示承認が必要	GET /v1alpha1/trend-watch/catalog/reports/{id}
tvpulse_list_programs	無料	GET /v1alpha1/programs
tvpulse_get_program	無料	GET /v1alpha1/programs/{airing_id}
tvpulse_saved_search_create	作成は無料。日次実行は確認済みの1回あたりクレジットを消費	POST /v1/api/saved-searches/estimate, POST /v1/api/saved-searches
tvpulse_saved_search_list	無料。残高不足で自動停止した保存検索は、クレジット補充後に削除して作成し直すと実行されます	GET /v1/api/saved-searches
tvpulse_saved_search_delete	無料	DELETE /v1/api/saved-searches/{id}

クレジットと制限に関する注意

• OCR（画面内テキスト）とASR（音声）の件数は単位が異なるため、常に別々に返され、合算されません。
• 対応局は関東・関西の主要地上波局です。プリセット tokyo または osaka（sun を含む）、 あるいは局コードを明示して指定できます。標準料金で両地域の局を1回で指定できます。 未対応の局コードは入力検証エラーになります。再試行する前に局コードを確認してください。
• sampled_programs は返された証跡からサンプリングされた番組であり、ランキングでも全放送の 網羅的な記録でもありません。
• 投影（trend/breakdown/sampled_programs/evidence）がまだ計算中の場合は 0 や空配列ではなく {"status": "unavailable", "reason": ...} として返されます。tvpulse_get_search_results （無料）で再取得してください。
• tvpulse_export_records_status のポーリングは無料です。
• 同一セッション内で全く同じ検索条件を再度呼び出した場合、新規課金せずに既存の search_id を 無料で返します（refresh=true で強制的に再見積もり・再実行）。
• 課金系ツールは自動リトライしません（二重課金防止）。実行ごとに専用の Idempotency-Key を使用します。

監視スキルの導入

Claude Codeプラグイン（方法1）を使う場合、スキルは自動的にインストールされます。手動セットアップ （方法3）の場合は、skill/tvpulse-tv-monitoring/ を Claude Code がスキルを読み込む場所へコピーして ください:

cp -r skill/tvpulse-tv-monitoring ~/.claude/skills/tvpulse-tv-monitoring
# or, project-scoped:
cp -r skill/tvpulse-tv-monitoring .claude/skills/tvpulse-tv-monitoring

Claude Desktop（方法2）の場合は sdks/mcp/scripts/sync-distribution.sh が作成する distribution/skill-build/tvpulse-tv-monitoring.zip を「設定 > Capabilities > Skills」から アップロードしてください。

トラブルシューティング

• 「APIキーが設定されていません」と出る: いずれかの方法でAPIキーを設定してください （プラグイン/拡張機能ならインストール時のプロンプト、手動セットアップなら TVPULSE_API_KEY 環境変数）。tvpulse_check_connection を呼ぶとキーの発行先URLと、 お使いのクライアント別の設定手順が日本語で表示されます。
• 「APIキーが無効です」「401」エラー: キーが失効・削除されている可能性があります。 https://tvpulse.io/account/api-keys で新しいキーを発行し、設定し直してください。未設定時とは 別の、無効キー専用のメッセージが表示されます。
• uv/uvx が見つからない: https://docs.astral.sh/uv/getting-started/installation/ の手順でインストールしてください。全3つのインストール方法が uvx を前提としています。
• 承認プロンプトが表示されない / confirm_token が使えない: MCP elicitationに対応していない クライアントでは、承認が必要な呼び出しは実行されず needs_confirmation と confirm_token （10分間有効、1回限り）が返るだけです。表示された内容を確認したうえで、同じツールを confirm_token を添えて再実行してください。トークンが期限切れの場合は見積もりからやり直します。

---

English

Local (stdio) MCP server exposing the TVPulse customer API to Claude Code and other MCP clients, built around /v1/api/searches: one billed search-definition create followed by free trend/breakdown/programs/evidence projections, so one analyst question costs one charge instead of three. Every spend goes through a human-approval gate before it runs (see "Approval flow and budgets" below).

Install

There are three ways to install. If unsure, use the Claude Code plugin (no manual config, API key stored securely).

Option 1: Claude Code plugin (recommended)

/plugin marketplace add https://tvpulse.io/claude/marketplace.json
/plugin install tvpulse@tvpulse

Requires Claude Code 2.1.224 or later. You'll be prompted for your API key at install time (stored securely, never shown in chat). The confirm-above-credits threshold and session budget default to 20 and 200 credits. The monitoring skill installs automatically. See distribution/claude-plugin/README.md for details.

Prerequisite: uv installed (provides uvx).

Option 2: Claude Desktop extension (.mcpb bundle)

Download tvpulse.mcpb and double-click it, or add it via Claude Desktop's Settings > Extensions > Install from file. You'll be prompted for your API key on first launch. Same uv/uvx prerequisite as Option 1.

Option 3: Manual setup (Claude Code, pinned version)

uvx tvpulse-mcp==1.1.0

claude mcp add tvpulse \
  -e TVPULSE_API_KEY=your-api-key \
  -e TVPULSE_CONFIRM_ABOVE_CREDITS=20 \
  -e TVPULSE_SESSION_BUDGET_CREDITS=200 \
  -- uvx tvpulse-mcp==1.1.0

Set TVPULSE_API_KEY via environment, never in chat. For the dev gateway:

claude mcp add tvpulse \
  -e TVPULSE_API_KEY=your-dev-api-key \
  -e TVPULSE_BASE_URL=https://gateway.dev.tvpulse.io \
  -e TVPULSE_CONFIRM_ABOVE_CREDITS=20 \
  -e TVPULSE_SESSION_BUDGET_CREDITS=200 \
  -- uvx tvpulse-mcp==1.1.0

TVPULSE_BASE_URL defaults to production (https://gateway.tvpulse.io) if unset.

Frame view_url links point at TVPULSE_WEB_BASE_URL (default https://tvpulse.io). For dev, also add -e TVPULSE_WEB_BASE_URL=https://dev.tvpulse.io.

No API key yet?

With any install method, calling a tool such as tvpulse_check_connection without a key returns a message (Japanese first, then English) with the issuance URL (https://tvpulse.io/account/api-keys) and per-client setup instructions.

After registering, confirm the connection first by asking:

TVPulseに接続できているか確認して

(or in English, "check whether TVPulse is connected") -- this calls the free tvpulse_check_connection tool, which validates the API key and shows the base URL, balance, and configured budgets.

Approval flow and budgets

tvpulse_search_mentions and a non-dry-run tvpulse_export_records_create both go through the same approval gate:

1. Estimate first (free) and always show the interpretation block (keyword/mode, Japanese station names + region, explicit JST window, CM policy) before spending.
2. Hosted calls return needs_confirmation for every positive-credit estimate. Local stdio calls at or under TVPULSE_CONFIRM_ABOVE_CREDITS (default 20 credits) run.
3. Above the stdio threshold, the server asks via MCP elicitation or returns needs_confirmation with a confirm_token (single-use, 10-minute TTL) if the client cannot elicit. Show the estimate to the user and re-call the same tool with the token only after the user approves.
4. Exceeding TVPULSE_SESSION_BUDGET_CREDITS (default 200 credits, cumulative for this session) is a hard refusal that no argument can override; restart the session with a higher value if more spend is genuinely needed.
5. outcome=enterprise_review is a pricing-tier issue, not a budget issue -- raising credits will not fix it; the request needs a narrower scope or help from the TVPulse administrator.

Important: the hosted approval threshold is fixed at zero. The stdio threshold and session budget are environment settings, not tool arguments. Replaying a confirm_token does not itself prove human approval, so clients must wait for an explicit user decision.

Tools

See the table above (same tools, same routes). Highlights:

• tvpulse_search_mentions is the main tool: keyword or 1-10 terms + JST window + station preset/list. Multiple spellings in terms default to OR and form one search/one credit charge; the response's query.query_expansion reports server-expanded variants. It returns separate OCR-observation and ASR-segment counts by day and by station, sampled_programs (programs seen in the sampled evidence, not a ranking), and a capped page of evidence, all timestamps normalized to explicit +09:00 JST strings. Unavailable projections are returned as {"status": "unavailable", "reason": ...}, never as 0 or an empty list.
• tvpulse_get_search_results (free) re-fetches projections for an existing search_id with bounded backoff, useful when some projections came back unavailable initially.
• tvpulse_trend_reports_list and tvpulse_trend_reports_quote are free. The first successful tvpulse_trend_reports_get read costs 5 credits once per organization/report ID; later reads of that ID, including after edits, are free. Show the quote and get explicit user approval before a first read, even when the configured threshold would auto-approve it.
• tvpulse_save_evidence_csv (free, local write) pages already-paid evidence for a search_id into an Excel-ready CSV: UTF-8 with BOM, JST timestamps, full untruncated text, Japanese station names. Refuses to overwrite an existing file unless overwrite=true. Stops at the 10,000-hit fair-use cap and reports truncated and truncation_message when it does.
• tvpulse_export_records_create / tvpulse_export_records_status use the /v1alpha1/exports job surface. Without keyword it is an unfiltered bulk export (gzip NDJSON, dry_run quote then approved submit). With keyword (plus mode AND/OR and format ndjson/csv) it exports matching records for exactly one search charge, uses the same estimate-then-confirm approval as a paid search, waits up to 45 seconds, and returns signed download URLs with total_hits, exported_count, truncated and truncation_message. One job stops at 10,000 hits (fair-use cap). Status polling is free; hosted servers return signed URLs and never write a local file.
• Evidence depth (evidence_limit, 1-10,000, default 10,000) does not change the price, and paging tvpulse_get_evidence (100 hits per page) is free. Search responses show a small first page plus a coverage sentence that says how many hits were retrieved, whether the result is complete, and the next step.
• visual search is never exposed by these tools (separate pilot modality/pricing); sources is limited to ocr/asr.
• Raw text/voice/combined search and X/news trend-card watches are not exposed in this MCP server. Daily saved searches for TV monitoring are available through the tools above.

Development

The MCP package requires Python 3.11 or later. The hosted image uses Python 3.12. Pillow 13.0.0 provides the image decoder security fixes and requires Python 3.11.

uv venv --python 3.12 .venv
uv pip install -p .venv/bin/python -e ".[dev]"
.venv/bin/python -m pytest tests/ -q
.venv/bin/python -m ruff check src/ tests/
.venv/bin/python -m mypy src/

The tvpulse SDK dependency resolves to the local ../python package during development via [tool.uv.sources] in pyproject.toml; the published package requires tvpulse>=1.0,<2.

Authenticated smoke test (hosted)

scripts/smoke_authenticated.py connects to hosted MCP with a user OAuth bearer token (tvpat_...), lists tools, calls tvpulse_current_org, tvpulse_list_channels and tvpulse_estimate (free, no search is run), and fails if any output contains pricing/upgrade/checkout/sales text, correlation_id or org_id. It prints check names only, never the token or response bodies. It is a dry run unless --execute is given. It targets dev only (--target-env dev); there is no production target, so a user token is never sent to production.

export MCP_SMOKE_BEARER_TOKEN=...   # token of the account under test
uv run python scripts/smoke_authenticated.py --target-env dev --execute
uv run python scripts/smoke_authenticated.py --target-env dev --execute \
  --expect-org-name "<org name of the account>"   # optional

Exit code: 0 pass, 1 check or connection failure, 2 token missing.

Skill install

With the Claude Code plugin (Option 1), the skill installs automatically. For manual setup (Option 3), bilingual TV-monitoring workflow guidance (cost rules, unit warnings, coverage limits, JST date-resolution examples) lives in skill/tvpulse-tv-monitoring/SKILL.md. Install it into ~/.claude/skills/tvpulse-tv-monitoring/ (user-wide) or .claude/skills/tvpulse-tv-monitoring/ (project-scoped) to have Claude load it automatically for TV-monitoring questions.

For Claude Desktop (Option 2), upload the zip produced by sdks/mcp/scripts/sync-distribution.sh at distribution/skill-build/tvpulse-tv-monitoring.zip via Settings > Capabilities > Skills.

Troubleshooting

• "No API key configured": set one via any install method (the plugin/extension prompt at install time, or the TVPULSE_API_KEY env var for manual setup). Calling tvpulse_check_connection shows the issuance URL and per-client setup steps.
• "Invalid API key" / 401: the key may be revoked or deleted. Issue a new one at https://tvpulse.io/account/api-keys and reconfigure it. This is a distinct message from the missing-key case.
• uv/uvx not found: install it from https://docs.astral.sh/uv/getting-started/installation/. All three install methods require uvx.
• No approval prompt shown / confirm_token not accepted: clients without MCP elicitation support won't auto-prompt; a call needing approval returns needs_confirmation with a confirm_token (single-use, 10-minute TTL) instead of running. Review what was shown, then re-call the same tool with that confirm_token. If it has expired, re-estimate and try again.