# 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](https://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

```bash
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`

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

```bash
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