litmos-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@litmos-mcp find user sarah.johnson@example.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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+
uvinstalledA 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-mcpRun from a local clone
git clone https://github.com/dbuxton/litmos-mcp
cd litmos-mcp
LITMOS_API_KEY=your_key uvx --from . litmos-mcpConfiguration
All configuration is via environment variables:
Variable | Required | Default | Description |
| Yes | — | Your Litmos API key |
| No |
| API region: |
| No |
| Source label sent with every API request |
Region endpoints
Region | Base URL |
|
|
|
|
|
|
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_hereOr 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 |
| Search users by name, email, username, or company |
| Retrieve a full user profile by encrypted user ID |
| List all users with pagination support |
| Get all courses assigned to a user with completion status |
| Get module-level results for a specific user/course pair |
| Get learning paths assigned to a user |
| List all courses in the organisation |
| Get teams a user belongs to |
Typical workflow
Find a user — use
litmos_search_userswith a name or email to get their encryptedId.Check training — use
litmos_get_user_courseswith thatIdto see all assigned courses and completion status.Drill into a course — use
litmos_get_user_course_resultswith the userIdand courseIdfor 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-mcpLicense
MIT
Available Tools
8 toolslitmos_get_userARead-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_resultsARead-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_coursesARead-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_pathsARead-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_teamsARead-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_coursesARead-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_usersARead-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_usersARead-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
Scored across 8 tools
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.
All tools follow the consistent pattern 'litmos_verb_noun' (e.g., litmos_get_user, litmos_list_courses), with clear verb-noun combinations.
8 tools is well-scoped for an LMS read-only integration, covering essential entities without unnecessary bloat.
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
Related MCP Connectors
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
Read-only MCP for AI usage profiles, leaderboards, stats, and docs; no writes or private data.
Read-only MCP server exposing a user ORANO library to their own AI agent.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Related MCP Servers
- AlicenseAqualityDmaintenanceRead-only MCP server that connects AI clients to Crescender's school asset, loan, member, and asset-comms API.6MIT
- FlicenseNot gradedqualityCmaintenanceMCP server for interacting with Rustici LRS via xAPI, enabling statement retrieval, analytics, and aggregation operations.-
- FlicenseAqualityCmaintenanceRead-only MCP server providing Wealthi's AI Coach with scoped access to student progress data from Firestore and Supabase, enabling AI to retrieve student profiles, progress, assessment results, and learning signals without direct database credentials.6-
- FlicenseBqualityDmaintenanceRead-only FastMCP server for Canvas LMS study data.10-