AlayaCare Server

An MCP (Model Context Protocol) server that bridges the AlayaCare home care platform with AI agents — including N8N AI Agent workflows powered by Claude or GPT.

Architecture

N8N Workflow
  └── AI Agent Node (LLM: Claude / GPT)
        └── MCP Client Node  ← built into N8N
              └── AlayaCare MCP Server  ← this project
                    └── AlayaCare REST API (basic auth)

Tools exposed to the AI agent

Tool	What it answers
list_psws	Who are all the active PSWs and where do they live?
get_psw	Details on a specific PSW
list_clients	Who are all the active clients and where are their service addresses?
get_client	Details on a specific client
get_visits	What visits are scheduled in a date range?
get_psw_schedule	What is a specific PSW's full schedule?
get_psw_utilization	Which PSWs are over/under-utilized?
find_nearest_clients	Which clients live closest to a given PSW?
find_nearest_psw_for_client	Which PSWs live closest to a given client?
analyze_schedule_travel	What are the travel distances between a PSW's visits on a given day?

Prerequisites

• Node.js 18+
• An AlayaCare account with API access enabled
• Basic auth credentials (username + password) for the AlayaCare API
• Addresses in AlayaCare must have latitude/longitude populated for geo tools to work (use a geocoding step or AlayaCare's built-in geocoding if available)

Setup

# 1. Clone and install
git clone https://github.com/deathracr/alayacare-mcp.git
cd alayacare-mcp
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env with your AlayaCare credentials

# 3. Build
npm run build

# 4. Run
npm start

Configuration (.env)

# Your AlayaCare instance URL
ALAYACARE_BASE_URL=https://yourcompany.alayacare.com

# Basic auth credentials
ALAYACARE_USERNAME=your_api_username
ALAYACARE_PASSWORD=your_api_password

# Transport mode: "stdio" for N8N stdio node, "sse" for HTTP
MCP_TRANSPORT=stdio

# Port — only used when MCP_TRANSPORT=sse
MCP_PORT=3000

Connecting to N8N

Option A: SSE transport (recommended for N8N cloud / remote)

1. Run the server with MCP_TRANSPORT=sse on a host reachable by N8N
2. In N8N, add an MCP Client node
3. Set the SSE URL to http://your-server:3000/sse

Option B: stdio transport (N8N self-hosted, same machine)

1. Run with MCP_TRANSPORT=stdio (default)
2. In N8N MCP node, choose stdio and point to node /path/to/dist/index.js

Example questions your AI agent can answer

• "Which PSWs are under-utilized this week?"
• "Find the 5 clients closest to PSW #42."
• "Show me all missed visits in the last 7 days."
• "How many hours is Sarah Johnson scheduled for next week?"
• "Which PSW lives closest to client #107?"
• "Analyze the travel efficiency of PSW #15's schedule for tomorrow."

Important notes

Geocoding: The distance-based tools (find_nearest_clients, find_nearest_psw_for_client, analyze_schedule_travel) require that addresses in AlayaCare have latitude and longitude fields populated. If your AlayaCare instance stores only street addresses, you will need to run a geocoding step to enrich the data.

API endpoint paths: AlayaCare API paths are configured in src/alayacare/client.ts. If your instance uses different URL patterns, update the paths in getEmployees, getPatients, and getVisits.

Rate limiting: The client paginates automatically (100 records per page). For large datasets, consider adding caching.