# Artefact Revenue Intelligence MCP Server

> **Three-dimensional revenue intelligence. Because demographics alone don't close deals.**

A methodology-driven MCP server for B2B revenue intelligence. Provides the **ICP Triangulation Framework™** (firmographics + behaviors + growth signals), RFM analysis, and pipeline health scoring through Claude, Cursor, and other MCP-compatible AI tools. Integrates with HubSpot CRM.

Artefact MCP Server is different from generic HubSpot CRUD wrappers because it embeds the Artefact Formula — battle-tested scoring models that go beyond traditional firmographic ICP models by triangulating across prospect profile, activity, and momentum.

## Core Tools

- [RFM Analysis](https://github.com/alexboissAV/artefact-mcp-server/blob/main/README.md#run_rfm--rfm-analysis): Scores clients on Recency, Frequency, Monetary value. Segments into 11 categories (Champions through Lost). Extracts ICP patterns from top performers. Supports B2B service, SaaS, and manufacturing presets.
- [ICP Triangulation Framework™](https://github.com/alexboissAV/artefact-mcp-server/blob/main/README.md#qualify--icp-triangulation-framework): Go beyond demographics. Scores prospects across three dimensions: 🏢 Firmographic Fit (who they are), 🎯 Behavioral Fit (what they're doing), 📈 Growth Signals (where they're heading). Returns 4-tier classification (Ideal/Strong/Moderate/Poor) with engagement strategy.
- [Pipeline Health Score](https://github.com/alexboissAV/artefact-mcp-server/blob/main/README.md#score_pipeline_health--pipeline-health-score): 0-100 health score analyzing velocity metrics, stage conversion rates, bottleneck identification, and at-risk deal detection.

## Methodology Resources

- methodology://scoring-model — ICP Triangulation Framework technical reference
- methodology://tier-definitions — 4-tier classification system
- methodology://rfm-segments — 11 RFM segment definitions
- methodology://spiced-framework — SPICED discovery framework
- methodology://data-requirements — HubSpot data setup and enrichment guide (READ THIS for ICP triangulation)

## Installation & Setup

- [PyPI Package](https://pypi.org/project/artefact-mcp/): `pip install artefact-mcp`
- [GitHub Repository](https://github.com/alexboissAV/artefact-mcp-server): Source code and development
- [Smithery](https://smithery.ai/server/artefact-revenue-intelligence): One-click install

**MCP Configuration:**
- **Recommended:** Use `python3 -m artefact_mcp` (Python always in PATH)
- **Alternative:** Use `uvx artefact-mcp` (may require full path: `which uvx`)
- **Troubleshooting:** See [README Troubleshooting section](https://github.com/alexboissAV/artefact-mcp-server#troubleshooting) if you see "Server disconnected" errors with uvx

## Data Requirements for ICP Triangulation

**IMPORTANT:** The `qualify` tool (ICP Triangulation Framework) requires specific data across all three dimensions:

### ✅ Native HubSpot Data (Firmographic + Partial Behavioral)
- **🏢 Firmographic Fit:** Industry, revenue, employees, geography (standard HubSpot properties)
- **🎯 Behavioral Fit (Partial):** Tech stack (custom property), content engagement (HubSpot workflows), purchase history (deal count)
- **Strategic Fit:** Decision-maker access, budget authority, strategic alignment (custom properties)

### ⚠️ Requires External Enrichment (Critical for Complete Triangulation)
- **📈 Growth Signals (Third Dimension):** HubSpot does NOT track hiring trends, funding rounds, product launches, expansion signals, or press mentions
- **Recommended:** Use Clay to enrich LinkedIn job postings, Crunchbase funding data, news mentions
- **Alternative:** Manual research during discovery calls, store in HubSpot custom property `growth_signals`

**Without growth signals enrichment:** You lose the third dimension of triangulation — prospect momentum and buying power indicators. Traditional firmographics alone miss the "where they're heading" signal.

**Read the full guide:** Call `methodology://data-requirements` resource for complete setup instructions and Clay integration workflow.

## Pro/Enterprise Configuration Features

**Custom Property Mapping** (Pro/Enterprise only):
- Map your HubSpot custom properties to ICP scoring dimensions
- Configure tech stack, growth signals, content engagement, and strategic fit properties
- Environment variable: `ARTEFACT_PROPERTY_MAPPING_PATH`
- Example: `property_mapping.example.json`

**Custom RFM Thresholds** (Pro/Enterprise only):
- Customize recency, frequency, and monetary scoring thresholds
- Supports percentile-based or fixed dollar thresholds
- Match thresholds to your business model and buying cycles
- Environment variable: `ARTEFACT_RFM_THRESHOLDS_PATH`
- Example: `rfm_thresholds.example.json`

**Configuration Validation**:
- `validate_configuration()` tool tests configs without API calls
- Shows what properties will be fetched and any configuration errors
- Secure validation: path traversal protection, file size limits, JSON schema validation

## Who Is This For

- B2B revenue teams using HubSpot who want AI-powered customer segmentation
- RevOps managers who need pipeline health analysis accessible from Claude or Cursor
- Consultants who deliver RFM analysis and ICP scoring to clients
- Developers building revenue intelligence integrations with MCP
