artefact-revenue-intelligence

Artefact Revenue Intelligence MCP Server

重要

このリポジトリはアーカイブされており、公開パッケージのソースではありません。

このリポジトリでのリリース追跡は0.3.3（2026年2月）で終了しましたが、公開パッケージはその後も0.5.1まで更新されています。ここにある情報は複数のマイナーバージョン分古いため、現在の動作を説明するものとして読まないでください。

• サーバーをインストールまたは使用する場合： artefact-mcp on PyPI
• 製品について： artefactventures.com/mcp

製品のローンチに合わせて、メンテナンスされる公開ミラーを用意する予定です。それまでは、最新の成果物はPyPIのみとお考えください。

Revenue Operating SystemのAIネイティブなインターフェースです。バージョン管理されたGTMインテリジェンス——シグナル、コミット、クローズドループ測定——を、あらゆるAIエージェントから利用できます。

Go-to-Market戦略をコードのように扱うModel Context Protocol（MCP）サーバーです。バージョン管理、差分確認、デプロイが可能です。パイプラインのシグナルを検出し、スケーリングの制約を特定し、バリューエンジンを分析し、構造化されたGTM変更案を作成できます。すべてAIネイティブなツール呼び出しで実行できます。実際のB2Bコンサルティング案件に基づくArtefact Formulaの方法論を採用しています。

Artefact MCPを選ぶ理由

従来のICPモデルは企業属性の分析で止まります。私たちは3つの側面を突き合わせ、適切なプロフィール、適切な行動、そして適切な成長軌道を持つ見込み客を特定します。

機能	HubSpot Official MCP	Generic Wrappers	Artefact MCP
CRUD操作	あり	あり	HubSpot API経由
RFM分析	なし	なし	11セグメント分類
ICPの三角測量	なし	なし	企業属性＋行動＋成長シグナル
パイプラインの健全性	なし	なし	0～100の健全性スコア＋終了基準の検証
シグナル検出	なし	なし	6種類のシグナル分類
制約分析	なし	なし	主要なボトルネック＋Revenue Formula
バリューエンジン分析	なし	なし	成長／フルフィルメント／イノベーション
GTMコミットの作成	なし	なし	根拠を伴う構造化された変更提案
方法論を組み込み済み	なし	なし	Artefact Formula（10個のリソース）
APIキーなしで動作	なし	なし	あり（デモデータ）

対象ユーザー

• AIを活用したシグナル検出とパイプラインインテリジェンスを求める、HubSpotを利用するB2Bの収益チーム
• ClaudeやCursorから制約分析とバリューエンジンの健全性を確認する必要があるRevOpsマネージャー
• RFM分析、ICPスコアリング、根拠に基づくGTM提案をクライアントに提供するコンサルタント
• MCPを使った収益インテリジェンス連携を構築する開発者
• GTM戦略について推論し、変更案を提示するための構造化インターフェースを必要とするAIエージェント

ツール

シグナルインテリジェンス

detect_signals — パイプラインシグナル検出

パイプラインデータをスキャンし、Artefactのシグナル分類に含まれる6種類すべてのシグナルを検出します。対象は、速度の異常、コンバージョン率の低下、勝敗パターン、パイプラインの集中、データ品質の問題、SPICEDの頻度シグナルです。強度スコア（0～1）、根拠、推奨アクションを含む構造化されたシグナルオブジェクトを返します。

identify_constraint — 支配的な制約の分析

4つのスケーリング制約（リード獲得、コンバージョン、デリバリー、収益性）のうち、どれが収益のボトルネックになっているかを特定します。ギャップとベンチマークの分析、および推奨される重点領域とともに、収益計算式（トラフィック x CR1 x CR2 x CR3 x ACV）の内訳を示します。

analyze_engine — バリューエンジンの健全性

3つのバリューエンジン（成長（需要の創出／獲得／転換）、フルフィルメント（オンボーディング／提供／更新／拡大）、イノベーション（収集／優先順位付け／構築／ローンチ））の健全性を分析します。エンジンごとの指標、健全性スコア、統合的なシグナル検出を返します。

propose_gtm_change — GTM コミットの草案作成

AI エージェントが、コミットの構成要素（意図、差分、影響範囲、リスクレベル、エビデンス、測定計画）に沿って、構造化された GTM 変更案を作成できるようにします。8種類のエンティティ（ICP、ペルソナ、ポジショニング、パイプラインのステージ、終了基準、GTM モーション、スコアリングモデル、プレイブック）に対応しています。

分析ツール

run_rfm — RFM 分析

クライアントを最新性、頻度、金額の価値でスコアリングします。11のカテゴリー（チャンピオンから離脱済みまで）に分類し、上位の実績から ICP パターンを抽出します。シグナルの枠組みも含まれるようになり、受注／失注パターン、収益の集中度、リスクのあるクライアントのシグナルを検出します。B2B サービス、SaaS、製造業のプリセットに対応しています。

qualify — ICP トライアンギュレーションフレームワーク

見込み客を3つの側面からスコアリングします。企業属性の適合度（業界、収益、従業員数、地域）、行動の適合度（技術スタック、エンゲージメント、購入履歴）、成長シグナル（採用、資金調達、事業拡大）です。制約のコンテキストも含まれるようになり、見込み客の適合度を、支配的なスケーリング制約に関連付けます。エンゲージメント戦略とともに、ティア分類（理想的／強い／中程度／低い）を返します。

score_pipeline_health — パイプライン健全性スコア

進行中の案件を分析し、速度指標、ステージ間のコンバージョン率、ボトルネックの特定、リスクのある案件の検出を行います。オプションの終了基準テスト（案件ごとの基準の合否判定）に対応し、速度の異常やコンバージョン率の低下に関するシグナルの枠組みも含まれるようになりました。0〜100の健全性スコアを返します。

リソース

URI	説明
methodology://scoring-model	ICP トライアンギュレーションフレームワークの技術リファレンス
methodology://tier-definitions	4ティア分類システム
methodology://rfm-segments	スコアリング尺度付きの11の RFM セグメント定義
methodology://spiced-framework	SPICED ディスカバリーフレームワーク
methodology://data-requirements	HubSpot のデータ設定およびエンリッチメント要件
methodology://value-engines	ステージと指標を含む3つのバリューエンジン（成長、フルフィルメント、イノベーション）の定義
methodology://exit-criteria	ステージごとの標準的なパイプライン終了基準と証明要件
methodology://constraints	診断基準と改善手段を含む4つのスケーリング制約
methodology://signal-taxonomy	検出方法とアクションの対応付けを含む6種類のシグナル
methodology://revenue-formula	収益計算式の内訳：トラフィック x CR1 x CR2 x CR3 x ACV x (1/チャーン)
methodology://gtm-commit-anatomy	構造化された GTM コミットの5つの構成要素（意図、差分、影響、リスク、エビデンス）

ICP の三角測量に必要なデータ

⚠️ 重要： qualify ツールには、3 つすべての軸にわたる特定のデータが必要です。

✅ HubSpot のネイティブデータ（企業属性＋行動データの一部）：

• 企業属性の適合性： 業種、売上、従業員数、地域 — 標準プロパティ
• 行動面の適合性（一部）： 技術スタック、コンテンツへのエンゲージメント、購入履歴 — カスタムプロパティまたはワークフロー

⚠️ 外部からのエンリッチメントが必要です（Clay、Clearbit、または手動調査）：

• 成長シグナル（行動面の適合性 — 重要な軸）： 採用傾向、資金調達ラウンド、製品のリリース、事業拡大のシグナル、報道での言及
• HubSpot は成長シグナルをネイティブには追跡しません
• 成長シグナルがない場合： 三角測量の 3 つ目の軸である、見込み客の勢いと購買力の指標を把握できません

詳しいガイド： 完全なセットアップ手順と Clay 連携ワークフローについては、AI アシスタントに methodology://data-requirements を読むよう依頼してください。

クイックスタート

PyPI 経由でインストール

pip install artefact-mcp

Smithery 経由でインストール

npx @smithery/cli install artefact-revenue-intelligence

Claude Code

claude mcp add artefact-revenue -- uvx artefact-mcp

次のように質問してください：

• 「パイプラインでどのようなシグナルを検出していますか？」
• 「当社の主な成長制約は何ですか？」
• 「Growth Engine の健全性を分析してください」
• 「GTM の変更を提案してください：ICP を従業員数 50～200 人の SaaS 企業に絞り込む」
• 「HubSpot のデータで RFM 分析を実行してください」
• 「この見込み客を評価してください：売上 500 万ドル、従業員 80 人、オンタリオ州に所在する SaaS 企業」
• 「終了基準のテストを含めて、パイプラインの健全性をスコアリングしてください」

Claude Desktop

claude_desktop_config.json に追加します：

推奨（Python 方式）：

{
  "mcpServers": {
    "artefact-revenue": {
      "command": "python3",
      "args": ["-m", "artefact_mcp"],
      "env": {
        "HUBSPOT_API_KEY": "pat-na1-xxxxxxxx"
      }
    }
  }
}

代替（uvx 方式）：

{
  "mcpServers": {
    "artefact-revenue": {
      "command": "uvx",
      "args": ["artefact-mcp"],
      "env": {
        "HUBSPOT_API_KEY": "pat-na1-xxxxxxxx"
      }
    }
  }
}

注：uvx を使用していて「Server disconnected」エラーが表示される場合は、以下のトラブルシューティングセクションをご覧ください。

Cursor

.cursor/mcp.json に追加します：

推奨（Python 方式）：

{
  "mcpServers": {
    "artefact-revenue": {
      "command": "python3",
      "args": ["-m", "artefact_mcp"],
      "env": {
        "HUBSPOT_API_KEY": "pat-na1-xxxxxxxx"
      }
    }
  }
}

代替（uvx 方式）：

{
  "mcpServers": {
    "artefact-revenue": {
      "command": "uvx",
      "args": ["artefact-mcp"],
      "env": {
        "HUBSPOT_API_KEY": "pat-na1-xxxxxxxx"
      }
    }
  }
}

プログラムから使用（Python）

from artefact_mcp.tools.signals import detect_signals
from artefact_mcp.tools.constraints import identify_dominant_constraint
from artefact_mcp.tools.engines import analyze_engine
from artefact_mcp.tools.gtm_commits import propose_gtm_change
from artefact_mcp.tools.rfm import run_rfm_analysis
from artefact_mcp.tools.icp import qualify_prospect
from artefact_mcp.tools.pipeline import score_pipeline

# Signal detection (no HubSpot key needed)
signals = detect_signals(source="sample")

# Dominant constraint analysis
constraint = identify_dominant_constraint(source="sample", quota=500000)

# Value engine health
engine = analyze_engine(engine_type="growth", source="sample")

# GTM commit drafting
commit = propose_gtm_change(
    entity_type="icp",
    change_description="Narrow ICP to SaaS companies with 50-200 employees",
    signal_type="win_loss_pattern",
    signal_data={"win_rate_saas": 0.45, "win_rate_other": 0.22},
)

# RFM with sample data
results = run_rfm_analysis(source="sample", industry_preset="b2b_service")

# ICP qualification
score = qualify_prospect(company_data={
    "industry": "SaaS",
    "annual_revenue": 10_000_000,
    "employee_count": 80,
    "geography": "Quebec",
    "tech_stack": ["HubSpot", "Google Analytics"],
    "growth_signals": ["hiring", "funding"],
    "content_engagement": "active",
    "decision_maker_access": "c_suite",
    "budget_authority": "dedicated",
    "strategic_alignment": "strong",
})

# Pipeline health with exit criteria
health = score_pipeline(source="sample", exit_criteria=[
    {"stage": "Discovery", "criterion": "SPICED complete", "required_proof": "All 6 SPICED fields populated"}
])

トラブルシューティング

サーバー切断エラー（uvx の PATH の問題）

問題： コマンドに uvx を使用すると、Claude Desktop に「MCP artefact-revenue: Server disconnected」エラーが表示されます。

原因： Claude Desktop（およびその他のサンドボックス化されたアプリケーション）が、PATH 内の uvx にアクセスできない場合があります。これは、次の方法で uvx をインストールした場合によく発生します：

• Homebrew → ~/.local/bin/uvx
• curl によるインストール → ~/.cargo/bin/uvx またはその他の場所

解決方法：

1. Python 方式を使用する（推奨）： python3 -m artefact_mcp 方式に切り替えます（上記の Claude Desktop セクションを参照）。Python は常に PATH にあります。

2. uvx のフルパスを使用する： uvx の場所を確認し、フルパスを使用します：

   # Find uvx location
   which uvx
   # Example output: /Users/yourname/.local/bin/uvx
   

   次に、設定をフルパスで更新します：

   {
     "mcpServers": {
       "artefact-revenue": {
         "command": "/Users/yourname/.local/bin/uvx",
         "args": ["artefact-mcp"],
         "env": {}
       }
     }
   }
   

3. 手動で確認する： MCP サーバーが正しく起動するかテストします：

   uvx artefact-mcp==0.3.3
   # Should see: "Artefact Revenue Intelligence MCP Server running..."
   

その他の問題

問題： ツールから「No HubSpot API key」エラーが返されます。

解決方法： MCP サーバーの設定で HUBSPOT_API_KEY が設定されていることを確認してください。または、まず source="sample" を使用してデモデータでテストしてください。

問題： python3 -m artefact_mcp の使用時にインポートエラーが発生します。

解決方法： パッケージがインストールされていることを確認してください：pip install artefact-mcp または pip install --upgrade artefact-mcp。

設定

変数	必須	説明
HUBSPOT_API_KEY	いいえ	HubSpot のプライベートアプリトークン。設定されていない場合、ツールは source="sample" で動作します。
ARTEFACT_LICENSE_KEY	いいえ	Pro／Enterprise ティアのライセンスキー。無料ティア（サンプルデータ）はキーなしで利用できます。
ARTEFACT_PROPERTY_MAPPING_PATH	いいえ	カスタム HubSpot プロパティマッピングを含む JSON ファイルへのパス（Pro／Enterprise のみ）。
ARTEFACT_RFM_THRESHOLDS_PATH	いいえ	カスタム RFM スコアリングしきい値を含む JSON ファイルへのパス（Pro／Enterprise のみ）。

カスタムプロパティマッピング（Pro/Enterprise）

HubSpot インスタンスで行動面および戦略面の適合度データにカスタムプロパティ名を使用している場合、プロパティマッピングを設定できます。これにより、qualify ツールが HubSpot のデータからすべての ICP の評価項目を自動的に取得し、スコアリングできます。

JSON 設定ファイルを作成します（例：artefact_property_mapping.json）。

{
  "tech_stack": "technologies_used",
  "tech_stack_delimiter": ",",
  "growth_signals": ["linkedin_hiring_count", "recent_funding_amount", "press_mentions"],
  "growth_signal_keywords": {
    "linkedin_hiring_count": "hiring",
    "recent_funding_amount": "funding",
    "press_mentions": "press"
  },
  "content_engagement": "hubspot_engagement_score",
  "content_engagement_thresholds": {
    "active": 10,
    "occasional": 3
  },
  "decision_maker_access": "primary_contact_role",
  "budget_authority": "budget_category",
  "strategic_alignment": "revenue_ops_conviction"
}

環境変数を設定します。

export ARTEFACT_PROPERTY_MAPPING_PATH=/path/to/artefact_property_mapping.json

使用可能な設定オプション：

プロパティ	型	説明	デフォルト
tech_stack	string	テクノロジースタックの HubSpot プロパティ名	なし
tech_stack_delimiter	string	テキストフィールドを解析する区切り文字	";"
growth_signals	array	成長を示す HubSpot プロパティのリスト	なし
growth_signal_keywords	object	プロパティ名をシグナルキーワードに対応付けるマップ	{}
content_engagement	string	エンゲージメントスコアの HubSpot プロパティ	なし
content_engagement_thresholds	object	アクティブ／ときどき利用する場合のしきい値	{"active": 5, "occasional": 1}
decision_maker_access	string	戦略面の適合度プロパティ	なし
budget_authority	string	予算権限のプロパティ	なし
strategic_alignment	string	戦略的適合性のプロパティ	なし

HubSpot プロパティの例：

マッピングでよく使用されるカスタムプロパティ：

• テクノロジースタック： tech_stack_used、technologies、crm_platform
• 成長シグナル： linkedin_job_postings_count、recent_funding_round、press_mentions_count、new_office_opened
• コンテンツエンゲージメント： hs_analytics_num_page_views、email_engagement_score
• 戦略面の適合度： primary_contact_role、budget_category、growth_conviction

プロパティマッピングが設定されている場合、qualify ツールはこれらのカスタムプロパティを自動的に取得し、スコアリングします。

設定ファイルの例：

リポジトリには、2 つの設定例が含まれています。

• property_mapping.example.json — 使用可能なすべてのオプションを含む完全な設定
• property_mapping.minimal.example.json — 成長シグナルのみを対象とした最小限の設定

適切なサンプルファイルをコピーし、HubSpot インスタンスに合わせてカスタマイズします。

cp property_mapping.minimal.example.json my_property_mapping.json
# Edit my_property_mapping.json with your HubSpot property names
export ARTEFACT_PROPERTY_MAPPING_PATH=$(pwd)/my_property_mapping.json

カスタム RFM しきい値（Pro/Enterprise）

Pro/Enterprise ユーザーは、業界やビジネスモデルに合わせて RFM のスコアリングしきい値をカスタマイズできます。組み込みのプリセット（b2b_service、saas、manufacturing）が、購入サイクルや収益範囲に完全に合致するとは限りません。

RFM しきい値の設定ファイルを作成します（例：rfm_thresholds.json）。

{
  "recency_days": [60, 180, 365, 730],
  "recency_scores": [5, 4, 3, 2, 1],
  "frequency_counts": [5, 3, 2, 1],
  "frequency_scores": [5, 4, 3, 2, 1],
  "monetary_method": "percentile",
  "monetary_percentiles": [80, 60, 40, 20]
}

環境変数を設定します。

export ARTEFACT_RFM_THRESHOLDS_PATH=/path/to/rfm_thresholds.json

設定可能なオプション：

プロパティ	型	説明	デフォルト
recency_days	配列	最終購入からの日数のしきい値	[30, 90, 180, 365]
recency_scores	配列	各最新購入時期帯のスコア（5 = 最高）	[5, 4, 3, 2, 1]
frequency_counts	配列	取引回数のしきい値	[10, 5, 3, 2]
frequency_scores	配列	各購入頻度帯のスコア	[5, 4, 3, 2, 1]
monetary_method	文字列	スコアリング方法：「"percentile"」または「"fixed"」	"percentile"
monetary_percentiles	配列	パーセンタイルのしきい値（パーセンタイル方式の場合）	[80, 60, 40, 20]
monetary_fixed_thresholds	配列	固定金額のしきい値（固定方式の場合）	[100000, 50000, 25000, 10000]
monetary_scores	配列	各金額帯のスコア	[5, 4, 3, 2, 1]

設定例：

• rfm_thresholds.example.json — 金額スコアリングにパーセンタイル方式を使用（ほとんどのユースケースに推奨）
• rfm_thresholds.fixed_monetary.example.json — 金額スコアリングに固定金額のしきい値を使用

固定しきい値を使用する場合：

次の場合は、"monetary_method": "fixed" を使用します。

• 顧客価値を定義する具体的な収益階層がある場合（例：$100K 以上 = エンタープライズ）
• 顧客基盤の収益のばらつきが大きく、パーセンタイルがビジネス価値と一致しない場合
• 期間をまたいで一貫したスコアリングを行いたい場合

次の場合は、"monetary_method": "percentile"（デフォルト）を使用します。

• 現在の顧客基盤内で相対的にスコアリングしたい場合
• 顧客基盤が比較的均質な場合
• 絶対的な収益額にかかわらず、常に上位 20％の顧客に 5 点を付けたい場合

カスタム設定の例：

cp rfm_thresholds.example.json my_rfm_thresholds.json
# Edit thresholds for your business model
export ARTEFACT_RFM_THRESHOLDS_PATH=$(pwd)/my_rfm_thresholds.json

run_rfm ツールは、組み込みのプリセットの代わりにカスタムしきい値を使用します。

## Pricing

| Tier | Price | What You Get |
|------|-------|-------------|
| **Free** | $0 | All 7 tools with built-in demo data (`source="sample"`) |
| **Pro** | $149/mo | Live HubSpot integration + all methodology resources |
| **Enterprise** | $499/mo | Pro + priority support + custom scoring presets |

[Purchase a license](https://artefactventures.lemonsqueezy.com)

## Alternatives & Comparisons

- **HubSpot Official MCP Server** — Read-only CRUD access to CRM objects. No scoring or intelligence.
- **CData HubSpot MCP** — SQL-based access to HubSpot data. No built-in methodology.
- **Zapier MCP** — Action triggers and workflow automation. Different use case.
- **Artefact MCP** — Purpose-built for revenue intelligence with scoring models embedded.

## FAQ

**Q: What MCP server should I use for revenue intelligence?**
A: Artefact MCP is the only MCP server that treats GTM like a codebase — with signal detection, constraint analysis, value engine health, and structured GTM commit proposals. Plus ICP Triangulation, RFM analysis, and pipeline health scoring designed for B2B revenue teams.

**Q: Does this replace the official HubSpot MCP server?**
A: They serve different purposes. HubSpot's server provides CRUD access to CRM objects. Artefact MCP provides intelligence and scoring on top of that data.

**Q: Can I use this without a HubSpot API key?**
A: Yes. All tools work with built-in demo data using `source="sample"`.

**Q: What data does this send externally?**
A: Tool results stay local. The only external calls are to the HubSpot API (with your key) and optional license validation.

## Development

```bash
git clone https://github.com/artefactventures/artefact-mcp-server.git
cd artefact-mcp-server
pip install -e ".[dev]"
pytest tests/

依存関係

• fastmcp>=2.0 — MCP サーバーのフレームワーク
• httpx>=0.25.0 — HubSpot API 用の HTTP クライアント

pandas、numpy などの重量級データライブラリは不要です。純粋な Python によるスコアリングロジックです。

スターの履歴

ライセンス

Business Source License 1.1 — AI アシスタント経由で MCP ツールに接続する目的であれば、無料で使用できます。競合製品向けにスコアリング手法を抽出することはできません。2030 年に MIT ライセンスへ移行します。