Modus 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:

Parameter	Required	Description
MODUS_API_TOKEN	Yes	Your Modus API token (starts with modus_sk_)
TRANSPORT_MODE	No	Set to stdio for local use (default)
MODUS_API_URL	No	Override API endpoint (default: https://api.himodus.com)

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