Modus MCP Server

A Model Context Protocol (MCP) server that provides access to Modus's RevOps and Sales Insights API for retrieving headcount data, attrition predictions, sales performance metrics, and capacity planning insights.

Features

• Headcount & Workforce Analytics - Get current headcount, attrition risks, and historical attrition trends

• Sales Performance Metrics - Access performance leaderboards, team metrics, and individual employee insights

• Capacity Planning - Retrieve quarterly capacity, hiring timelines, and revenue gap analysis

• AI-Powered Insights - Generate sales insights across 30+ categories and benchmark-driven recommendations

• Flexible Filtering - Filter by department, role, date ranges, and custom parameters

• Quota & Territory Management - Access quota assignments and territory details

Prerequisites

Before you begin, ensure you have:

• Node.js 18 or higher

• Modus API Access - A valid Modus account with API access

• Modus API Token - Generated from your Modus dashboard

Getting Your Modus API Token

1. Log into dashboard.himodus.com

2. Go to Configuration → Developer

3. Click "Generate New API Key"

4. Name: MCP Server Access

5. Select all read permissions

6. Copy the generated key (starts with modus_sk_...)

Security Note: Keep this token secure. Never share it or commit it to version control.

Installation

1. Install Dependencies

npm install

2. Build (Optional)

The server runs directly from the source file modus-mcp-server.js. No build step is required unless you're packaging for distribution.

Configuration

Claude Desktop Setup

Add the Modus MCP server to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "modus-revops": {
      "command": "node",
      "args": ["/absolute/path/to/modus-mcp-server.js"],
      "env": {
        "MODUS_API_TOKEN": "modus_sk_your_api_token_here",
        "TRANSPORT_MODE": "stdio"
      }
    }
  }
}

Configuration Parameters:

Important: Replace /absolute/path/to/modus-mcp-server.js with the full path to the server file on your system.

Testing the Server

Run the server directly to verify configuration:

export MODUS_API_TOKEN="modus_sk_your_token_here"
export TRANSPORT_MODE="stdio"
node modus-mcp-server.js

Expected output:

Modus MCP Server running on stdio
Connected to: https://api.himodus.com

Available Tools

The Modus MCP server provides 14 tools for accessing RevOps and sales data:

Headcount & Workforce

modus_get_current_headcount

Get current headcount by team, role, or department with filtering.

Parameters:

• department (optional): Filter by department name (e.g., "Sales", "Engineering")

• role (optional): Filter by job role (e.g., "Account Executive", "SDR")

• status (optional): Filter by employment status - ACTIVE (default) or INACTIVE

Returns: Employee data including roles, departments, employment status, and headcount summaries by department and role.

modus_get_attrition_risks

Get ML-powered attrition risk predictions with confidence scores and risk factors.

Parameters:

• threshold (optional): Minimum risk threshold (0-1). Default: 0.7 (70% risk)

• department (optional): Filter by department name

• fresh (optional): Generate fresh insights (slower). Default: false (uses cached data)

Returns: At-risk employees with confidence scores, risk factors, predicted termination dates, performance metrics, and Gong activity signals.

modus_get_historical_attrition

Get historical attrition metrics for trend analysis.

Parameters:

• days (optional): Time period - 90, 180 (default), or 365 days

• department (optional): Filter by department name

Returns: Attrition rates, counts, and list of terminated employees over the specified period.

modus_get_open_positions

Get open job requisitions and hiring forecast by quarter.

Parameters:

• status (optional): Filter by status - OPEN (default), DRAFT, CLOSED, or ALL

• department (optional): Filter by department name

Returns: Open positions with status, department, planned start dates, and summaries by status/quarter.

modus_get_ramp_profiles

Get ramp time profiles showing new hire productivity curves by role.

Parameters:

• role (optional): Job role to get ramp data for (e.g., "Account Executive")

Returns: Month-by-month productivity percentages showing how long new hires take to reach full productivity.

Sales Performance

modus_get_performance_leaderboard

Get top sales performers across key metrics.

Parameters:

• year (optional): Year for performance data

• quarter (optional): Quarter number (1-4)

• month (optional): Month number (1-12)

• limit (optional): Number of top performers per metric. Default: 6

Returns: Ranked list of top performers for opportunities created/won, pipeline created, bookings, ASP, and close rate.

modus_get_team_performance

Get team performance overview with performance labels and rankings.

Parameters:

• year (optional): Year for performance data

• quarter (optional): Quarter number (1-4)

• month (optional): Month number (1-12)

• limit (optional): Maximum employees to return. Default: 50

• offset (optional): Pagination offset

• sortBy (optional): Sort by revenue, bookings, opportunities, pipeline, ASP, or closeRate

• sortOrder (optional): asc or desc

Returns: Employee performance metrics with labels (Top performer, High potential, At risk), revenue, bookings, opportunities, pipeline, ASP, and close rate.

modus_get_employee_insights

Get individual employee performance insights with AI analysis.

Parameters:

• employeeId (required): Employee ID to analyze

Returns: Detailed performance summary with ramp progress, quota attainment, revenue, pipeline coverage, and AI-generated insights about trends and concerns.

Capacity Planning & Revenue Analysis

modus_get_quarterly_capacity

Get quarterly capacity breakdown with waterfall metrics. Preferred tool for revenue gap analysis.

Parameters:

• scenarioId (optional): Scenario ID to analyze

Returns: 5 quarters of data (3 previous + current + 1 future) showing beginning/end capacity, revenue targets, gaps, attrition impact, backfills, and capacity at risk.

modus_get_sales_breakdown

Get comprehensive sales breakdown with hiring/capacity analysis.

Parameters:

• period (optional): Auto-detected or specify: YTD, QUARTER, YEAR, CUSTOM_RANGE, LAST_12_MONTHS, NEXT_12_MONTHS

• year (optional): Year to analyze (e.g., 2025)

• quarter (optional): Quarter number (1-4) - auto-sets period to QUARTER

• startDate (optional): Start date (YYYY-MM-DD) - requires endDate

• endDate (optional): End date (YYYY-MM-DD) - requires startDate

• scenarioId (optional): Scenario ID to analyze

Returns: Month-by-month capacity projections with revenue gaps, hiring needs, targets, attrition impact, and quarterly waterfall metrics.

modus_get_hiring_timeline

Get planned hiring timeline with ramp details and quota assignments.

Parameters:

• year (optional): Year for hiring timeline. Default: 2025

• scenarioId (optional): Scenario ID to analyze

Returns: Hiring schedule with time to hire, start/end dates, territory assignments, monthly ramp percentages, and quarterly quotas.

Insights & Recommendations

modus_get_sales_insights

Get AI-powered sales insights across 30+ categories with recommendations.

Parameters:

• categories (optional): Comma-separated list (e.g., REVENUE_GAP,ATTRITION_RISK,TERRITORY_PERFORMANCE)

  • Available: REVENUE_GAP, HEADCOUNT_PLANNING, CAPACITY_UTILIZATION, ATTRITION_RISK, ATTRITION_BACKFILLS, PIPELINE_COVERAGE, WIN_RATE_SHIFTS, SALES_CYCLE_BOTTLENECK, TERRITORY_PERFORMANCE, TERRITORY_DESIGN, TERRITORY_LOAD_MGMT, MARKET_EXPANSION, COMPETITIVE_ANALYSIS, SKILLS_GAP, and 20+ more

• timeframe (optional): JSON timeframe (e.g., {"months": 12})

• includeRecommendations (optional): Include AI recommendations. Default: true

• limit (optional): Maximum insights to return (max: 100). Default: 50

• skipCache (optional): Force fresh generation (slower). Default: false

Returns: Detailed insights with recommendations, confidence scores, severity levels, and affected employees/territories.

modus_get_benchmark_insights

Get benchmark-driven sales insights comparing company metrics to industry standards.

Parameters:

• category (optional): Filter by territory, performance, or recommendations

• force (optional): Force fresh generation bypassing cache. Default: false

Returns: Company metrics (OTE, quotas, attrition rates), industry benchmarks with sources, variance analysis, and actionable recommendations. Optimized for fast retrieval (<500ms).

Quota & Territory Management

modus_get_quota_assignments

Get quota assignments by employee and territory.

Parameters:

• year (optional): Year for quota assignments

• search (optional): Search employee names

• region (optional): Filter by region

• role (optional): Filter by job role

Returns: Employee quota assignments with quarterly and annual quotas, territory details, and regional breakdowns.

API Reference

The MCP server connects to the Modus API at https://api.himodus.com by default. All tools authenticate using your Modus API token.

Base URL: https://api.himodus.com Authentication: Bearer token (Authorization: Bearer modus_sk_...) Timeout: 30 seconds per request

License

MIT

Contributing

Contributions welcome! Please open an issue or submit a pull request