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)

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