# litmos-mcp

An [MCP](https://modelcontextprotocol.io/) server that provides read-only access to the [Litmos](https://www.litmos.com/) LMS REST API. Expose training completion status, user profiles, course results, and learning path data to any MCP-compatible AI client.

## Prerequisites

- Python 3.11+
- [`uv`](https://docs.astral.sh/uv/) installed
- A Litmos API key (Account Owner access required)

## Quick start

### Run directly from GitHub

```bash
LITMOS_API_KEY=your_key uvx --from git+https://github.com/dbuxton/litmos-mcp litmos-mcp
```

### Run from a local clone

```bash
git clone https://github.com/dbuxton/litmos-mcp
cd litmos-mcp
LITMOS_API_KEY=your_key uvx --from . litmos-mcp
```

## Configuration

All configuration is via environment variables:

| Variable          | Required | Default       | Description                                  |
|-------------------|----------|---------------|----------------------------------------------|
| `LITMOS_API_KEY`  | Yes      | —             | Your Litmos API key                          |
| `LITMOS_REGION`   | No       | `us`          | API region: `us`, `eu`, or `au`              |
| `LITMOS_SOURCE`   | No       | `litmos-mcp`  | Source label sent with every API request     |

### Region endpoints

| Region | Base URL                          |
|--------|-----------------------------------|
| `us`   | `https://api.litmos.com/v1.svc`   |
| `eu`   | `https://api.litmoseu.com/v1.svc` |
| `au`   | `https://api.litmos.com.au/v1.svc`|

## MCP client configuration

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "litmos": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/dbuxton/litmos-mcp", "litmos-mcp"],
      "env": {
        "LITMOS_API_KEY": "your_key_here",
        "LITMOS_REGION": "us"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add litmos \
  --command uvx \
  --args "--from,git+https://github.com/dbuxton/litmos-mcp,litmos-mcp" \
  --env LITMOS_API_KEY=your_key_here
```

Or add directly to `.claude/mcp.json` in your project:

```json
{
  "mcpServers": {
    "litmos": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/dbuxton/litmos-mcp", "litmos-mcp"],
      "env": {
        "LITMOS_API_KEY": "your_key_here"
      }
    }
  }
}
```

## Available tools

| Tool | Description |
|------|-------------|
| `litmos_search_users` | Search users by name, email, username, or company |
| `litmos_get_user` | Retrieve a full user profile by encrypted user ID |
| `litmos_list_users` | List all users with pagination support |
| `litmos_get_user_courses` | Get all courses assigned to a user with completion status |
| `litmos_get_user_course_results` | Get module-level results for a specific user/course pair |
| `litmos_get_user_learning_paths` | Get learning paths assigned to a user |
| `litmos_list_courses` | List all courses in the organisation |
| `litmos_get_user_teams` | Get teams a user belongs to |

### Typical workflow

1. **Find a user** — use `litmos_search_users` with a name or email to get their encrypted `Id`.
2. **Check training** — use `litmos_get_user_courses` with that `Id` to see all assigned courses and completion status.
3. **Drill into a course** — use `litmos_get_user_course_results` with the user `Id` and course `Id` for module-level scores and attempt counts.

## API notes

- The Litmos REST API enforces a limit of **100 requests per minute** per API key. The server surfaces a clear error if this is exceeded.
- All tools are **read-only** — no write operations are exposed.
- Encrypted IDs returned by list/search endpoints must be used verbatim with other tools; do not attempt to decode or construct them manually.

## Development

```bash
git clone https://github.com/dbuxton/litmos-mcp
cd litmos-mcp
uv sync
LITMOS_API_KEY=your_key uv run litmos-mcp
```

## License

MIT