npm package: @spaik/mcp-server-attio
Description: Model Context Protocol server for Attio CRM with AI-powered Revenue Intelligence Platform
Author: SPAIK
Latest version: 2.0.2

# Attio MCP Server

This is a Model Context Protocol (MCP) server that provides comprehensive integration with [Attio CRM](https://attio.com). It enables AI assistants to interact with Attio data through a variety of tools for managing records, objects, lists, tasks, and more, with specialized features for sales pipeline optimization, revenue operations, and customer success.

**Standalone npx package for use with Claude Desktop and other MCP clients**

Developed by SPAIK (www.spaik.io)

## Features

### Core CRM Features
- **Records Management**: Create, update, search, and retrieve records across all Attio objects
- **Object & Schema Operations**: Manage custom objects and their attributes
- **Lists Management**: Create and manage lists for organizing records
- **Task Management**: Create, update, and track tasks linked to records
- **Bulk Operations**: Import multiple records at once
- **Notes & Comments**: Add notes to records
- **Webhooks**: Set up real-time event monitoring
- **Resources**: Access workspace configuration and available objects

### 🚀 Sales Pipeline Optimization Features (NEW)

#### Lead Scoring & Qualification
- **Automated Lead Scoring**: Calculate lead scores based on customizable criteria (company size, engagement, budget, timeline, authority)
- **Activity Tracking**: Track and score lead activities (email opens, website visits, content downloads, meetings)
- **Lead Qualification**: Qualify leads using BANT, MEDDIC, or CHAMP frameworks with automated recommendations

#### Pipeline Analytics
- **Velocity Analysis**: Analyze time spent in each stage, identify bottlenecks, and track conversion rates
- **Stalled Deal Detection**: Automatically identify deals that need attention with risk levels and suggested actions
- **Pipeline Health Metrics**: Monitor win rates, average deal sizes, and sales cycle lengths

#### Sales Automation
- **Follow-Up Sequences**: Create automated nurture, demo follow-up, and proposal sequences
- **Task Templates**: Generate stage-specific task lists adjusted for deal value
- **Smart Reminders**: AI-powered reminders based on deal characteristics, stage, and activity

#### Advanced Forecasting
- **AI-Powered Forecasts**: Generate revenue forecasts with confidence scenarios (committed, best case, worst case)
- **Historical Analysis**: Use win rate data to improve forecast accuracy
- **Period Breakdown**: Monthly and quarterly forecast views with deal-level details

### Revenue Operations (RevOps) Features

#### Revenue Analytics & Forecasting
- **Pipeline Analytics**: Analyze sales velocity, conversion rates, and stage progression
- **Revenue Forecasting**: Generate multi-scenario forecasts with confidence levels
- **Deal Scoring**: AI-powered deal prioritization based on value, stage, and engagement

#### Cross-Functional Alignment
- **Marketing Attribution**: Track ROI across campaigns, sources, and channels
- **Automated Handoffs**: Create workflows for seamless team transitions
- **Lead Scoring**: Score and prioritize leads based on behavior and fit

#### Performance & Compensation
- **Team Performance Tracking**: Individual and team metrics with leaderboards
- **Commission Calculation**: Automated commission calculations with tiers and accelerators
- **Activity Analytics**: Correlate activities to outcomes

#### Financial Integration
- **Subscription Metrics**: Calculate MRR, ARR, churn rate, and customer LTV
- **Contract Management**: Track contract values and renewal dates
- **Revenue Recognition**: Monitor deferred revenue and compliance

#### Data Governance
- **Data Quality Audits**: Identify duplicates, missing data, and inconsistencies
- **Intelligent Merging**: Merge duplicate records while preserving all data
- **Validation Rules**: Enforce data standards and completeness

### Customer Success Features (NEW)
- **Health Score Tracking**: Calculate and monitor customer health scores based on multiple factors
- **Churn Risk Detection**: Identify at-risk customers with automated alerts
- **Customer Metrics**: Track usage, engagement, and satisfaction metrics
- **Lifetime Value Analysis**: Calculate CLV and revenue forecasting
- **Success Plans**: Create structured onboarding and adoption plans
- **Automated Check-ins**: Schedule QBRs and regular customer touchpoints
- **Success Reporting**: Generate comprehensive customer success dashboards

### 🧠 Revenue Intelligence Platform (NEW)

Transform your Attio CRM into an AI-powered Revenue Intelligence system that helps startup founders increase revenue by 30-40% through predictive insights and automated workflows.

#### Unified Revenue Score™
- **Holistic Scoring**: Single metric (0-100) combining lead quality, deal momentum, and customer health
- **Trend Analysis**: Track score changes over time with historical data
- **Automated Updates**: Real-time scoring as data changes
- **Actionable Insights**: Specific recommendations based on score components

#### Predictive Analytics
- **Deal Predictions**: AI-powered close probability, expected close date, and risk identification
- **Churn Predictions**: Identify at-risk customers 60-90 days before churn
- **Expansion Identification**: Automatically surface upsell/cross-sell opportunities
- **Revenue Forecasting**: Multi-scenario forecasts with confidence levels

#### Revenue Automation
- **Smart Workflows**: Create automated workflows for lead nurture, deal acceleration, and customer success
- **Intelligent Task Creation**: AI-generated tasks based on deal stage and customer health
- **Alert System**: Real-time notifications for critical revenue events
- **Cross-functional Handoffs**: Seamless transitions between teams

#### Revenue Analytics
- **Attribution Analysis**: Multi-touch attribution across all channels
- **Velocity Optimization**: Identify and fix pipeline bottlenecks
- **Health Monitoring**: Real-time revenue health dashboards
- **Natural Language Queries**: Ask questions like "Show me deals closing this month worth over 50k"

#### AI-Powered Insights
- **Daily Revenue Briefings**: Automated insights on opportunities and risks
- **Action Recommendations**: Prioritized next best actions for each record
- **Pattern Recognition**: Identify successful patterns to replicate
- **Anomaly Detection**: Spot unusual trends before they impact revenue

## Prerequisites

- Node.js 18+ 
- An Attio account with API access
- Attio API key (get one from your [Attio settings](https://app.attio.com/settings/api-keys))

## 🔒 Security Notice

**Important**: Never pass your API key as a command-line argument. Always use environment variables to keep your credentials secure.

## Quick Start

The fastest way to use this server with Claude Desktop:

```bash
# Set your API key as an environment variable (recommended)
export ATTIO_API_KEY="your_api_key"
npx @SPAIK/mcp-server-attio

# Or use a .env file for local development
echo "ATTIO_API_KEY=your_api_key" > .env
npx @SPAIK/mcp-server-attio
```

### Claude Desktop Configuration

Add to your Claude Desktop config file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "attio": {
      "command": "npx",
      "args": ["@SPAIK/mcp-server-attio"],
      "env": {
        "ATTIO_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Development Setup

### 1. Clone and Install

```bash
git clone <repository-url>
cd mcp-server-attio
npm install

# Copy the example environment file
cp .env.example .env
# Edit .env and add your API key
```

### 2. Build the Server

```bash
npm run build
```

### 3. Test Locally

```bash
# Set your API key
export ATTIO_API_KEY="your_api_key"

# Run the server
./dist/index.js

# Run tests
npm test

# Run with inspector
npm run inspect
```

## Integrating with AI Tools

Once published to npm, you can integrate the Attio MCP server with various AI tools that support the Model Context Protocol.

### Publishing to npm

```bash
# The package is already configured as @SPAIK/mcp-server-attio
npm publish
```

### Integration Examples

#### Using with MCP Inspector

```bash
# Test your server with the official MCP Inspector
npx @modelcontextprotocol/inspector ./dist/index.js YOUR_API_KEY


### Verifying the Integration

After setting up the integration with Claude Desktop, you can verify it's working by:

1. Restart Claude Desktop after updating the configuration
2. Start a new conversation and ask: "What Attio tools are available?"
3. Try a simple command like: "Show me the Attio workspace info"

Common commands to test:
```
// List all available tools
What Attio tools are available?

// Get workspace information
Show me the Attio workspace info

// List objects
List all Attio objects in my workspace

// Create a test record
Create a new person in Attio with name "Test User" and email "test@example.com"
```

### Troubleshooting

If the integration isn't working:

1. **Check npm package**: Ensure the package is published and accessible
2. **Verify API key**: Ensure your Attio API key is correctly set in the environment variable
3. **Check logs**: Look for error messages in Claude Desktop's logs
4. **Validate API key**: Ensure your Attio API key has the necessary permissions
5. **Test locally**: Run `./dist/index.js YOUR_API_KEY` to test the server directly

## Available Tools

### Records Management

#### `create_record`
Create a new record in any Attio object.

```json
{
  "object_type": "people",
  "attributes": {
    "name": "John Doe",
    "email_addresses": ["john@example.com"],
    "phone_numbers": ["+1234567890"]
  }
}
```

#### `update_record`
Update an existing record.

```json
{
  "object_type": "people",
  "record_id": "rec_123",
  "attributes": {
    "job_title": "Senior Developer"
  }
}
```

#### `get_record`
Retrieve a specific record.

```json
{
  "object_type": "companies",
  "record_id": "rec_456"
}
```

#### `search_records`
Search for records with optional filters.

```json
{
  "object_type": "people",
  "query": "john",
  "filters": [
    {
      "attribute": "job_title",
      "operator": "contains",
      "value": "developer"
    }
  ],
  "limit": 25
}
```

### Object & Schema Management

#### `list_objects`
Get all available objects in your workspace.

#### `get_object_schema`
Get detailed schema information for an object.

```json
{
  "object_type": "people"
}
```

#### `create_custom_object`
Create a new custom object type.

```json
{
  "api_slug": "projects",
  "singular_noun": "Project",
  "plural_noun": "Projects"
}
```

#### `add_attribute`
Add a new attribute to an object.

```json
{
  "object_type": "projects",
  "api_slug": "budget",
  "title": "Budget",
  "type": "number",
  "is_required": false
}
```

### Lists Management

#### `create_list`
Create a new list for organizing records.

```json
{
  "name": "Hot Leads",
  "api_slug": "hot_leads",
  "parent_object": "people"
}
```

#### `add_to_list`
Add a record to a list.

```json
{
  "list_id": "list_123",
  "record_id": "rec_789"
}
```

#### `get_list_entries`
Get all entries in a list.

```json
{
  "list_id": "list_123",
  "limit": 100
}
```

### Task Management

#### `create_task`
Create a new task with optional linked records.

```json
{
  "content": "Follow up with customer",
  "linked_records": [
    {
      "target_object": "companies",
      "target_record_id": "rec_123"
    }
  ],
  "deadline": "2024-12-31T23:59:59Z"
}
```

#### `update_task`
Update task details or status.

```json
{
  "task_id": "task_123",
  "is_completed": true
}
```

#### `list_tasks`
List tasks with optional filters.

```json
{
  "is_completed": false,
  "limit": 50
}
```

#### `complete_task`
Mark a task as completed.

```json
{
  "task_id": "task_123"
}
```

### Sales Pipeline Optimization Tools

#### `calculate_lead_score`
Calculate a lead score based on multiple criteria with recommendations.

```json
{
  "record_id": "rec_123",
  "object_type": "people",
  "custom_criteria": {
    "companySize": { "weight": 20, "ranges": { "small": 5, "medium": 10, "large": 20 } },
    "engagement": { "weight": 30, "emailOpens": 2, "websiteVisits": 3, "contentDownloads": 5 }
  }
}
```

Returns a score (0-100), grade (A-D), breakdown by category, and actionable recommendations.

#### `track_lead_activity`
Track and log lead activities with automatic engagement scoring.

```json
{
  "record_id": "rec_123",
  "activity_type": "content-download",
  "details": "Downloaded pricing guide",
  "score_impact": 10
}
```

#### `qualify_lead`
Qualify a lead using BANT, MEDDIC, or CHAMP frameworks.

```json
{
  "record_id": "rec_123",
  "framework": "BANT",
  "responses": {
    "budget": 50000,
    "authority": "decision-maker",
    "need": "Critical business requirement",
    "timeline": "this-quarter"
  }
}
```

#### `analyze_pipeline_velocity`
Analyze pipeline velocity metrics and identify bottlenecks.

```json
{
  "deal_object_type": "deals",
  "days_back": 90
}
```

Returns stage metrics, conversion rates, bottlenecks, and overall pipeline health.

#### `identify_stalled_deals`
Find deals that haven't been updated recently and need attention.

```json
{
  "deal_object_type": "deals",
  "threshold_days": 30
}
```

Returns deals with risk levels, suggested actions, and days since last update.

#### `create_follow_up_sequence`
Create an automated follow-up sequence for leads.

```json
{
  "record_id": "rec_123",
  "sequence_type": "nurture"
}
```

Available sequences: nurture, demo-follow-up, proposal-follow-up, or custom.

#### `generate_task_templates`
Generate stage-specific task templates for deals.

```json
{
  "stage": "proposal",
  "deal_value": 100000
}
```

Returns prioritized task lists adjusted for deal value and stage.

#### `create_smart_reminders`
Create intelligent reminders based on deal characteristics.

```json
{
  "deal_id": "deal_123"
}
```

Automatically creates reminders for at-risk deals, approaching deadlines, and required actions.

#### `generate_sales_forecast`
Generate AI-powered sales forecast with multiple scenarios.

```json
{
  "forecast_period": 90
}
```

Returns committed, best case, worst case, and most likely revenue scenarios.

### Utility Tools

#### `bulk_import`
Import multiple records at once.

```json
{
  "object_type": "people",
  "records": [
    {
      "name": "Alice Smith",
      "email_addresses": ["alice@example.com"]
    },
    {
      "name": "Bob Johnson",
      "email_addresses": ["bob@example.com"]
    }
  ]
}
```

#### `generate_sales_report`
Generate a comprehensive sales report with deals, companies, and contact emails.

```json
{
  "days_back": 7,
  "deal_object_type": "deals",
  "include_contacts": true
}
```

This tool will:
- Fetch all deals created in the specified time period
- Retrieve associated company information for each deal
- Collect all contact emails from those companies
- Calculate summary statistics (total value, stage breakdown)
- Return a formatted report with all contact emails

#### `add_note`
Add a note to a record.

```json
{
  "target_object": "companies",
  "target_record_id": "rec_123",
  "content": "Had a great meeting, moving forward with the deal"
}
```

#### `get_workspace_info`
Get information about the current workspace.

### Revenue Intelligence Tools

#### `calculate_revenue_score`
Calculate unified revenue score across lead, deal, and customer lifecycle.

```json
{
  "record_type": "companies",
  "record_id": "rec_123"
}
```

Returns a comprehensive score (0-100) with insights and recommendations.

#### `predict_revenue_outcomes`
Generate AI predictions for deals and customer churn.

```json
{
  "prediction_type": "deal",  // or "churn"
  "record_id": "deal_456"
}
```

#### `identify_expansion_opportunities`
Find upsell, cross-sell, and renewal opportunities.

```json
{
  "customer_id": "company_789"
}
```

#### `generate_revenue_insights`
Get AI-powered insights across your revenue pipeline.

```json
{
  "insight_types": ["deals", "customers", "pipeline"]
}
```

#### `monitor_revenue_health`
Real-time monitoring with configurable alerts.

```json
{
  "alert_thresholds": {
    "pipeline_coverage": 3,
    "win_rate_min": 20
  }
}
```

#### `query_revenue_natural`
Query revenue data using natural language.

```json
{
  "query": "Show me all deals closing this month worth over 50k"
}
```

#### `create_webhook`
Create a webhook for real-time events.

```json
{
  "target_url": "https://your-app.com/webhook",
  "events": ["record.created", "record.updated"]
}
```

### Revenue Operations (RevOps) Tools

#### `analyze_pipeline`
Analyze sales pipeline metrics including velocity, conversion rates, and stage progression.

```json
{
  "deal_object_type": "deals",
  "date_range_days": 90,
  "group_by": "stage"  // Options: "stage", "owner", "source", "product"
}
```

Returns comprehensive pipeline analysis including:
- Total deals and pipeline value
- Average deal size and days to close
- Win/loss rates
- Stage conversion rates
- Pipeline velocity metrics
- Grouped analysis by selected dimension

#### `forecast_revenue`
Generate revenue forecasts based on pipeline data and historical performance.

```json
{
  "deal_object_type": "deals",
  "forecast_months": 3,
  "confidence_levels": true,
  "include_recurring": false
}
```

Provides three forecast scenarios:
- Conservative: Only high-probability deals (>70%)
- Likely: Probability-weighted forecast
- Optimistic: 90% close rate scenario

#### `score_deals`
Score and prioritize deals based on multiple factors.

```json
{
  "deal_object_type": "deals",
  "include_closed": false,
  "scoring_factors": ["value", "stage", "age", "activity", "completeness"]
}
```

Scores deals on a 0-100 scale considering:
- Deal value (0-30 points)
- Sales stage (0-25 points)
- Deal age (0-20 points)
- Recent activity (0-15 points)
- Data completeness (0-10 points)

#### `calculate_lead_attribution`
Calculate marketing attribution and ROI for leads and deals.

```json
{
  "people_object_type": "people",
  "deal_object_type": "deals",
  "attribution_window_days": 90
}
```

Analyzes attribution by:
- Lead source
- Campaign
- Channel
- Calculates ROI and win rates for each

#### `create_handoff_workflow`
Create automated handoff workflows between teams.

```json
{
  "workflow_type": "sales_to_cs",  // Options: "sales_to_cs", "marketing_to_sales", "cs_to_sales", "custom"
  "trigger_conditions": [
    {
      "field": "status",
      "operator": "equals",
      "value": "closed_won"
    }
  ],
  "actions": [
    {
      "type": "create_task",
      "details": {
        "content": "Schedule onboarding call",
        "assignee": "cs_team"
      }
    }
  ],
  "source_object": "deals"
}
```

#### `calculate_team_performance`
Calculate team and individual performance metrics.

```json
{
  "team_member_ids": ["member_123", "member_456"],  // Optional, analyzes all if empty
  "period_days": 30,
  "metrics": ["activity", "pipeline", "conversion", "velocity"]
}
```

Returns:
- Activity metrics (tasks, deals created/updated)
- Pipeline metrics (total deals, value, stage distribution)
- Conversion metrics (win rate, revenue generated)
- Velocity metrics (average days to close, stalled deals)

#### `calculate_commissions`
Calculate sales commissions based on configurable rules.

```json
{
  "commission_rules": {
    "base_rate": 0.1,  // 10% base commission
    "tiers": [
      { "threshold": 50000, "rate": 0.12 },
      { "threshold": 100000, "rate": 0.15 }
    ],
    "accelerators": [
      { "condition": "deal_size > 25000", "multiplier": 1.2 },
      { "condition": "new_logo", "multiplier": 1.5 }
    ]
  },
  "period": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
  }
}
```

#### `calculate_subscription_metrics`
Calculate key subscription metrics including MRR, ARR, churn, and LTV.

```json
{
  "subscription_object_type": "subscriptions",
  "company_object_type": "companies",
  "date_range_months": 12
}
```

Calculates:
- Monthly Recurring Revenue (MRR)
- Annual Recurring Revenue (ARR)
- Gross and net churn rates
- Customer lifetime value (LTV)
- Average revenue per account (ARPA)
- Monthly cohort analysis

#### `audit_data_quality`
Audit data quality across objects and identify issues.

```json
{
  "object_types": ["people", "companies", "deals"],
  "check_types": ["duplicates", "completeness", "consistency", "validation"]
}
```

Identifies:
- Duplicate records
- Missing required fields
- Incomplete records
- Invalid data formats
- Provides data quality score

#### `merge_duplicate_records`
Merge duplicate records intelligently.

```json
{
  "object_type": "people",
  "primary_record_id": "rec_123",
  "duplicate_record_ids": ["rec_456", "rec_789"],
  "merge_strategy": "most_complete"  // Options: "keep_primary", "most_complete", "most_recent"
}
```

Intelligently merges records by:
- Preserving all data
- Combining arrays (emails, phones)
- Using most complete/recent values
- Creating audit trail
- Adding merge notes

### Customer Success Tools

#### `calculate_health_score`
Calculate customer health score based on multiple weighted factors.

```json
{
  "company_id": "rec_123",
  "metrics": {
    "usage_score": 85,
    "engagement_score": 70,
    "support_score": 90,
    "payment_score": 100,
    "adoption_score": 60
  },
  "weights": {
    "usage": 0.3,
    "engagement": 0.2,
    "support": 0.2,
    "payment": 0.2,
    "adoption": 0.1
  }
}
```

This calculates a weighted health score and updates the company record with the score, status (healthy/needs_attention/at_risk), and individual metric scores.

#### `identify_churn_risks`
Identify customers at risk of churning based on multiple factors.

```json
{
  "days_inactive": 30,
  "health_score_threshold": 60,
  "include_payment_issues": true,
  "limit": 50
}
```

Returns a prioritized list of at-risk customers with risk levels (critical/high/medium) and specific risk factors.

#### `track_customer_metrics`
Update customer usage and engagement metrics.

```json
{
  "company_id": "rec_123",
  "metrics": {
    "daily_active_users": 45,
    "monthly_active_users": 120,
    "feature_adoption": {
      "dashboard": true,
      "api": true,
      "integrations": false
    },
    "last_login_date": "2024-01-20T10:30:00Z",
    "api_calls_count": 15000,
    "nps_score": 8
  }
}
```

Updates company metrics and calculates trends like MAU growth and feature adoption rate.

#### `calculate_customer_lifetime_value`
Calculate CLV and key revenue metrics.

```json
{
  "company_id": "rec_123",
  "monthly_revenue": 5000,
  "start_date": "2023-01-15",
  "expansion_revenue": 2000,
  "churn_probability": 0.15
}
```

Calculates expected lifetime, CLV, and updates revenue-related attributes on the company.

#### `create_success_plan`
Create structured success plans with milestones and automated tasks.

```json
{
  "company_id": "rec_123",
  "plan_type": "onboarding",
  "milestones": [
    {
      "title": "Initial Setup Complete",
      "description": "All integrations connected and data imported",
      "due_days": 7,
      "success_criteria": "3+ integrations active, 1000+ records imported"
    },
    {
      "title": "First Value Achievement",
      "description": "Customer achieves first measurable business outcome",
      "due_days": 30,
      "success_criteria": "10% efficiency improvement documented"
    }
  ],
  "assigned_to": "member_456"
}
```

Creates a success plan with a dedicated list and tasks for each milestone.

#### `generate_customer_success_report`
Generate comprehensive customer success analytics.

```json
{
  "time_period_days": 30,
  "segment": "at_risk",
  "include_recommendations": true
}
```

Generates a detailed report with:
- Customer health distribution
- Revenue at risk
- Average health scores
- NPS analysis
- Actionable recommendations

#### `schedule_customer_check_in`
Automate customer check-ins and QBRs.

```json
{
  "company_id": "rec_123",
  "check_in_type": "quarterly",
  "topics": [
    "Review business outcomes",
    "Discuss expansion opportunities",
    "Address any blockers",
    "Plan next quarter goals"
  ],
  "start_date": "2024-02-01",
  "assignee_id": "member_456"
}
```

Creates recurring check-in tasks with preparation notes and topics.

## Resources

The server provides read-only resources that can be accessed by AI assistants:

- **workspace_info**: Current workspace configuration and details
- **available_objects**: List of all available objects in the workspace

## Prompts

The server includes helpful prompts for common workflows:

### Sales & CRM Prompts
- **import_contacts_csv**: Step-by-step guide for importing contacts from CSV
- **create_sales_pipeline**: Guide for setting up a complete sales pipeline
- **task_automation**: Instructions for automating task creation
- **weekly_sales_report**: Guide for generating weekly sales reports with contact emails

### Customer Success Prompts
- **setup_health_scoring**: Complete guide for implementing customer health scoring
- **churn_prevention_workflow**: Automated workflows for preventing customer churn
- **customer_onboarding**: Structured onboarding automation setup
- **expansion_identification**: Systematic approach to finding upsell opportunities

## Use Cases

### 🎯 Sales Pipeline Optimization for Startup Founders

#### Increasing Conversion Rates

**1. Implement Lead Scoring**
```
Calculate lead scores for all contacts created this week
```

The AI will:
- Score leads based on company size, engagement, budget, timeline, and authority
- Provide A-D grades with specific recommendations
- Suggest routing rules (A grades to senior reps, B grades to standard team, etc.)
- Track conversion rates by score grade to optimize the model

**2. Qualify Leads Systematically**
```
Qualify this lead using BANT framework
```

The AI will:
- Run through Budget, Authority, Need, Timeline questions
- Calculate qualification score
- Provide specific recommendations for moving forward
- Suggest next steps based on qualification results

#### Reducing Sales Cycle Time

**1. Identify and Fix Pipeline Bottlenecks**
```
Analyze our pipeline velocity and show me the bottlenecks
```

The AI will:
- Calculate average time in each stage
- Identify stages taking 50%+ longer than average
- Show conversion rates between stages
- Provide specific actions to speed up slow stages

**2. Automate Follow-Up Sequences**
```
Create a demo follow-up sequence for this contact
```

The AI will automatically:
- Schedule thank you email (same day)
- Create task for sending demo recording (day 1)
- Schedule feedback call (day 3)
- Set proposal deadline (day 7)
- Create follow-up reminders (day 10)

**3. Manage Stalled Deals**
```
Show me all stalled deals that need attention
```

The AI will:
- Find deals with no activity in 30+ days
- Categorize by risk level (high/medium/low)
- Provide specific re-engagement actions
- Calculate total revenue at risk

#### Improving Deal Visibility and Forecasting

**1. Generate Accurate Forecasts**
```
Generate a sales forecast for the next quarter
```

The AI provides:
- Committed revenue (>70% probability)
- Best case scenario (all deals close)
- Most likely scenario (probability-weighted)
- Worst case scenario (80% of committed)
- Monthly breakdown with specific deals

**2. Create Smart Deal Reminders**
```
Create smart reminders for all my high-value deals
```

The AI will:
- Analyze each deal's stage, value, and activity
- Create reminders for deals needing attention
- Flag deals past expected close date
- Alert on high-value deals with no recent activity

### Weekly Sales Report Generation

The MCP server can generate comprehensive sales reports that include:
- All deals from a specified time period
- Associated company information
- Contact emails for all people linked to those companies
- Summary statistics and stage breakdown

Example usage in Claude Code:
```
Generate a weekly sales report for the last 7 days including all contact emails
```

The AI will use the `generate_sales_report` tool to:
1. Fetch deals from the past week
2. Get company details for each deal
3. Retrieve all contacts with their email addresses
4. Compile a formatted report with totals and email lists

This is perfect for:
- Weekly sales team meetings
- Email campaign targeting
- Pipeline analysis
- Customer outreach planning

### Revenue Operations for Startup Founders

#### Building a Scalable Revenue Engine

Startup founders can use the RevOps tools to build a data-driven revenue engine:

**1. Pipeline Velocity Optimization**
```
Analyze our sales pipeline velocity and identify bottlenecks
```

The AI will use `analyze_pipeline` to:
- Calculate average time in each stage
- Identify stages with highest drop-off rates
- Compare performance across reps and segments
- Provide actionable recommendations

**2. Revenue Forecasting & Planning**
```
Generate a 3-month revenue forecast with different scenarios
```

The AI will use `forecast_revenue` to:
- Create conservative, likely, and optimistic scenarios
- Factor in historical win rates by stage
- Account for seasonality
- Help with resource planning and hiring decisions

**3. Cross-Functional Alignment**
```
Calculate marketing attribution and ROI for our campaigns
```

The AI will use `calculate_lead_attribution` to:
- Track which campaigns drive revenue
- Calculate cost per acquisition by channel
- Identify highest ROI activities
- Optimize marketing spend allocation

**4. Team Performance & Compensation**
```
Calculate monthly commissions and performance metrics for the sales team
```

The AI will use `calculate_team_performance` and `calculate_commissions` to:
- Track individual and team performance
- Calculate commissions with tiers and accelerators
- Identify top performers and coaching opportunities
- Ensure fair and motivating compensation

**5. Data Quality & Governance**
```
Audit our CRM data quality and merge duplicates
```

The AI will use `audit_data_quality` and `merge_duplicate_records` to:
- Identify duplicate records
- Find missing critical data
- Merge duplicates intelligently
- Maintain clean, reliable data for decision-making

### Subscription Business Management

For SaaS and subscription businesses:

```
Calculate our key subscription metrics including MRR, churn, and LTV
```

The AI will use `calculate_subscription_metrics` to:
- Track MRR growth and cohort retention
- Calculate gross and net churn rates
- Determine customer lifetime value
- Identify expansion opportunities
- Monitor unit economics

### Automated Handoff Workflows

Create seamless transitions between teams:

```
Set up an automated handoff from sales to customer success when deals close
```

The AI will use `create_handoff_workflow` to:
- Define trigger conditions (e.g., deal closed won)
- Create onboarding tasks automatically
- Assign to appropriate team members
- Ensure no customer falls through the cracks

### Customer Health Monitoring

The server provides comprehensive health scoring to prevent churn:

Example usage:
```
Calculate health scores for all customers and identify those at risk
```

The AI will:
1. Use `calculate_health_score` to compute scores based on usage, engagement, support, and payment data
2. Run `identify_churn_risks` to find at-risk customers
3. Create intervention tasks for critical accounts
4. Generate recommendations for retention

### Automated Customer Success Plans

Create structured success plans for different customer lifecycle stages:

Example usage:
```
Create an onboarding plan for new customer Acme Corp with key milestones
```

The AI will use `create_success_plan` to:
1. Set up milestone-based tasks
2. Create a dedicated tracking list
3. Assign tasks to team members
4. Set success criteria for each stage

### Revenue Expansion Tracking

Identify and capture growth opportunities within existing customers:

Example usage:
```
Find customers ready for expansion based on usage and health metrics
```

The system will:
1. Analyze usage patterns approaching limits
2. Check health scores and engagement levels
3. Calculate potential expansion revenue
4. Create targeted upsell tasks

### Proactive Customer Engagement

Schedule automated check-ins based on customer tier and health:

Example usage:
```
Set up quarterly business reviews for all enterprise customers
```

This will:
1. Use `schedule_customer_check_in` to create recurring tasks
2. Include preparation checklists
3. Track outcomes and follow-ups
4. Maintain consistent customer touchpoints

## Testing

### Test with the MCP Inspector

```bash
npx @modelcontextprotocol/inspector http://localhost:3000/mcp
```

Note: You'll need to configure your API key in the Inspector's connection settings.

### Test Scripts

The repository includes test scripts in the `scripts/` directory:

```bash
# Test Attio MCP server (requires API key)
node scripts/test-attio-server.mjs http://localhost:3000 your_api_key_here

# Test Customer Success features (requires API key)
node scripts/test-customer-success.mjs http://localhost:3000 your_api_key_here

# Test standard HTTP client (for generic MCP testing)
node scripts/test-client.mjs http://localhost:3000

# Test SSE/streaming client
node scripts/test-streamable-http-client.mjs http://localhost:3000
```

The customer success test script will:
- Track customer metrics (usage, engagement, NPS)
- Calculate health scores
- Identify churn risks
- Create success plans with milestones
- Schedule automated check-ins
- Generate success reports

## API Rate Limits

Please be aware of Attio's API rate limits. The server includes error handling for rate limit responses, but it's recommended to implement appropriate throttling in your application.

## Error Handling

All tools include comprehensive error handling and will return descriptive error messages if operations fail. Common errors include:

- Missing required fields
- Invalid record/object IDs
- Insufficient permissions
- API rate limits exceeded

## Security

- **API Key Storage**: Your Attio API key is stored in your local MCP client configuration (Claude Code, Cursor, etc.) and is never exposed to the server logs
- **Never commit API keys**: Ensure your MCP client configuration files containing API keys are not committed to version control
- **Local Development**: When running locally, the API key is passed securely from the MCP client to the server
- **Production Deployment**: When deployed, the API key is transmitted securely over HTTPS from your MCP client
- **Access Control**: Consider implementing additional authentication layers if exposing the MCP server publicly
- **Workspace Isolation**: Use the optional `workspaceId` configuration to restrict access to specific Attio workspaces

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

For questions, feedback, or support, please contact us at info@spaik.io.

Maintained by SPAIK (www.spaik.io)

## License

MIT License - see LICENSE file for details