koalr-mcp
Koalr MCP server — connect your engineering metrics, deploy risk scoring, and DORA performance data to Claude, Cursor, Windsurf, and any MCP-compatible AI assistant.
👁 npm version
👁 smithery badge
Quick Start
Generate an API Key
- Go to app.koalr.com/settings/api-keys
- Create a new API key with the scopes you need
- Copy the key (shown once) — it starts with
koalr_
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"koalr": {
"command": "npx",
"args": ["-y", "koalr-mcp@latest"],
"env": {
"KOALR_API_KEY": "koalr_your_key_here"
}
}
}
}Cursor
Add to your Cursor MCP settings (~/.cursor/mcp.json):
{
"mcpServers": {
"koalr": {
"command": "npx",
"args": ["-y", "koalr-mcp@latest"],
"env": {
"KOALR_API_KEY": "koalr_your_key_here"
}
}
}
}Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"koalr": {
"command": "npx",
"args": ["-y", "koalr-mcp@latest"],
"env": {
"KOALR_API_KEY": "koalr_your_key_here"
}
}
}
}Claude Code (CLI)
claude mcp add koalr \ -e KOALR_API_KEY=koalr_your_key_here \ -- npx -y koalr-mcp@latest
Environment Variables
| Variable | Description | Default |
|---|---|---|
KOALR_API_KEY | Your Koalr API key (required). Starts with koalr_. | — |
KOALR_API_URL | Koalr API base URL (for self-hosted or local dev) | http://localhost:3001 |
MCP_TRANSPORT | Transport mode: stdio (default) or http
| stdio |
PORT | Port for HTTP transport mode | 3010 |
Available Tools
Organization
| Tool | Description |
|---|---|
get_org_health | Comprehensive org health: DORA tier, cycle time, teams, incidents |
get_well_being_summary | Developer well-being: focus time, meeting load, burnout signals |
DORA Metrics
| Tool | Description |
|---|---|
get_dora_summary | Deploy frequency, lead time, change failure rate, MTTR |
get_dora_trend | Weekly trend for any DORA metric |
Pull Requests
| Tool | Description |
|---|---|
get_pr_summary | Cycle time, throughput, review health metrics |
get_open_prs | Currently open PRs with age and risk indicators |
get_at_risk_prs | PRs at risk of being long-running or blocked |
Teams
| Tool | Description |
|---|---|
list_teams | All teams with IDs and member counts |
get_team | Team-level DORA and flow metrics |
list_team_members | Team roster with GitHub logins |
Repositories
| Tool | Description |
|---|---|
list_repositories | All repos with health scores |
get_repository | Repo metrics: deployment frequency, cycle time, contributors |
Developers
| Tool | Description |
|---|---|
get_developer | Individual developer metrics and recent activity |
list_top_contributors | Most active contributors by commits and PRs |
Search
| Tool | Description |
|---|---|
search | Search developers, repos, PRs, and teams by name |
Coverage
| Tool | Description |
|---|---|
get_coverage_summary | Test coverage by repository with trend |
Incidents
| Tool | Description |
|---|---|
list_recent_incidents | Recent incidents from PagerDuty/OpsGenie with MTTR |
AI Adoption
| Tool | Description |
|---|---|
get_ai_adoption_summary | GitHub Copilot and Cursor usage metrics |
get_ai_adoption_trend | AI tool adoption trend over time |
Example Prompts
Once connected, you can ask your AI agent things like:
- "What is our team's DORA performance tier this month?"
- "Show me all PRs that have been open for more than 3 days"
- "Which developers have the highest PR throughput on the backend team?"
- "How is our AI coding tool adoption trending?"
- "What was our MTTR for incidents last quarter?"
- "Find the auth-service repository and show me its deployment frequency"
HTTP Transport (Remote Hosting)
For hosting the MCP server remotely (e.g., at mcp.koalr.com):
MCP_TRANSPORT=http PORT=3010 KOALR_API_KEY=koalr_... node dist/index.js
The server exposes POST /mcp and GET /mcp endpoints following the MCP Streamable HTTP transport spec.
Local Development
# From repo root pnpm install pnpm exec turbo build --filter=koalr-mcp# Run in stdio mode (test with MCP Inspector) KOALR_API_KEY=koalr_... node apps/mcp/dist/index.js
# Run in HTTP mode MCP_TRANSPORT=http KOALR_API_KEY=koalr_... node apps/mcp/dist/index.js