Skip to main content
Glama

litmos-mcp

An MCP server that provides read-only access to the Litmos 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 installed

  • A Litmos API key (Account Owner access required)

Related MCP server: rustici-mcp-server

Quick start

Run directly from GitHub

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

Run from a local clone

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

{
  "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

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:

{
  "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

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

License

MIT

Available Tools

8 tools
litmos_get_userA
Read-onlyIdempotent

Retrieve the full profile for a single Litmos user by their encrypted ID.

Args: params: UserIdInput with: - user_id (str): Litmos encrypted user ID

Returns: str: JSON object with full user profile including Id, UserName, FirstName, LastName, Email, AccessLevel, Active, LastLogin, JobTitle, ExternalEmployeeId, CustomField1-10, and more.

Inputs: params (required). Returns: result

litmos_get_user_course_resultsA
Read-onlyIdempotent

Get detailed course and module-level results for a specific user/course pair.

Provides granular completion data including scores, attempt counts, and pass/fail status for each module within the course.

Args: params: UserCourseResultInput with: - user_id (str): Litmos encrypted user ID - course_id (str): Litmos encrypted course ID

Returns: str: JSON object with course-level fields plus a Modules array: { "Id": str, "Name": str, "Complete": bool, "PercentageComplete": float, "DateCompleted": str | null, "Modules": [{ "Id": str, "Name": str, "Completed": bool, "Score": int, "Passmark": int, "Attempt": int, "DateCompleted": str | null }, ...] }

Inputs: params (required). Returns: result

litmos_get_user_coursesA
Read-onlyIdempotent

Get all courses assigned to a user and their completion status.

This is the primary tool for checking training completion. Returns each course with completion status, percentage, dates, and whether the user is overdue or compliant.

Args: params: UserIdInput with: - user_id (str): Litmos encrypted user ID

Returns: str: JSON array of course assignments: [{ "Id": str, "Name": str, "Code": str, "Active": bool, "Complete": bool, "PercentageComplete": float, "AssignedDate": str, "StartDate": str | null, "DateCompleted": str | null, "Overdue": bool, "CompliantTill": str | null, "IsLearningPath": bool }, ...]

Inputs: params (required). Returns: result

litmos_get_user_learning_pathsA
Read-onlyIdempotent

Get all learning paths assigned to a user and their completion status.

Args: params: UserIdInput with: - user_id (str): Litmos encrypted user ID

Returns: str: JSON array of learning path assignments: [{ "Id": str, "Name": str, "Active": bool, "Complete": bool, "PercentageComplete": float, "AssignedDate": str, "StartDate": str | null, "DateCompleted": str | null, "AccessTillDate": str | null }, ...]

Inputs: params (required). Returns: result

litmos_get_user_teamsA
Read-onlyIdempotent

Get all teams that a user is assigned to.

Useful for understanding a user's organisational grouping or filtering completion data by team membership.

Args: params: UserIdInput with: - user_id (str): Litmos encrypted user ID

Returns: str: JSON array of teams: [{"Id": str, "Name": str, "TeamCodeForBulkImport": str, "ParentTeamId": str}, ...]

Inputs: params (required). Returns: result

litmos_list_coursesA
Read-onlyIdempotent

List courses available in the Litmos organisation.

Use the returned course IDs with litmos_get_user_course_results to fetch detailed results for a specific user/course combination.

Args: params: CourseListInput with: - limit (int): Records to return, default 100, max 1000 - start (int): Offset for pagination, default 0

Returns: str: JSON array of courses: [{"Id": str, "Name": str, "Code": str, "Active": bool, ...}, ...]

Inputs: params (required). Returns: result

litmos_list_usersA
Read-onlyIdempotent

List users in the Litmos organisation with pagination support.

Returns basic user info (Id, UserName, FirstName, LastName). Use litmos_get_user for full profiles or litmos_search_users to find a specific individual.

Args: params: UserListInput with: - limit (int): Records to return, default 100, max 1000 - start (int): Offset for pagination, default 0 - show_inactive (bool): Include inactive users, default False

Returns: str: JSON array of users: [{"Id": str, "UserName": str, "FirstName": str, "LastName": str}, ...]

Inputs: params (required). Returns: result

litmos_search_usersA
Read-onlyIdempotent

Search for Litmos users by name, email, username, or company.

Returns a list of matching users with their IDs. Use the returned Id values with other tools to retrieve training data for specific individuals.

Args: params: UserSearchInput with: - search (str): Search string (name, email, username, company)

Returns: str: JSON array of matching users: [{"Id": str, "UserName": str, "FirstName": str, "LastName": str}, ...]

Inputs: params (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct entity or relationship (user profile, user courses, course results, learning paths, teams, course list, user list, user search), with no overlapping purposes.

    Naming Consistency5/5

    All tools follow the consistent pattern 'litmos_verb_noun' (e.g., litmos_get_user, litmos_list_courses), with clear verb-noun combinations.

    Tool Count5/5

    8 tools is well-scoped for an LMS read-only integration, covering essential entities without unnecessary bloat.

    Completeness4/5

    Covers all main read operations for users, courses, learning paths, and teams. Minor gap: no tool to get details of a single course or list users in a team, but core workflows are supported.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers