This server provides a comprehensive Model Context Protocol (MCP) interface for athenahealth's clinical data and services, enabling AI-powered clinical decision support and automated healthcare workflows.
Core Capabilities:
Patient Management: Search patients by name, DOB, phone, or email; register new patients with demographic information
Clinical Data Access: Retrieve comprehensive patient summaries including allergies, prescriptions, problems, vitals, labs, and clinical alerts
Medication Management: Check drug interactions and create prescriptions with detailed dosage instructions
Appointment Management: Check available slots by department/date range and schedule appointments
Provider & Department Management: List departments and healthcare providers with specialty filtering
Encounter Management: Access patient encounters and create/update encounter details
AI-Powered Workflows: Generate clinical assessment prompts, medication reviews, and care plans
Technical Features:
Integration Flexibility: Works as MCP server for Claude Desktop or webhook bridge for n8n automation
Robustness: Automatic rate limiting, exponential backoff, comprehensive error handling, and network retry logic
HIPAA Compliance: Data sanitization, audit logging, role-based access controls, and secure encryption
Environment Notes: Patient search, registration, and provider/department listing work in sandbox. Most clinical features (drug interactions, prescriptions, appointments, encounters) require production environment access.
Built on Node.js runtime environment for server execution and dependency management
Uses npm package manager for dependency installation and project management
Implemented in TypeScript for type-safe development and compilation
athenahealth MCP Server
A Model Context Protocol (MCP) server that provides seamless integration with athenahealth's clinical data and services for AI-powered clinical decision support.
๐ Tool Status Overview
Status | Count | Percentage |
โ Working in Sandbox | 5 | 38% |
โ Not Working (Sandbox Limitations) | 8 | 62% |
๐งช Total Tools | 13 | 100% |
Features
๐ฅ Clinical Decision Support
Patient Data Access: Comprehensive patient information including demographics, medical history, and clinical data
Prescription Management: Medication history, drug interaction checking, and prescription creation (Production only)
Provider Management: Healthcare provider directory and practice information
Clinical Alerts: Real-time clinical decision support alerts and warnings (Production only)
Lab Results: Access to laboratory results and diagnostic reports (Production only)
Vital Signs: Patient vital signs history and trending (Production only)
๐ HIPAA Compliance
Data Sanitization: Automatic sanitization of sensitive healthcare data in logs
Audit Logging: Comprehensive audit trails for all data access and modifications
Access Controls: Role-based access controls and authentication
Data Encryption: Secure data transmission and storage
๐ AI-Powered Workflows
Clinical Assessment: AI-powered clinical assessment prompts
Medication Review: Automated medication review and optimization (handles sandbox limitations)
Care Plan Generation: Evidence-based care plan development
Clinical Summarization: Comprehensive patient clinical summaries
Installation
Prerequisites
Node.js 18.0.0 or later
athenahealth Developer Account and API credentials
TypeScript 5.0.0 or later
Quick Start
Option 1: Use with Claude Desktop (MCP)
Clone the repository
git clone https://github.com/ophydami/athenahealth-mcp-server.git cd athenahealth-mcp-serverInstall dependencies
npm installConfigure environment variables
cp config/environment.example .env # Edit .env with your athenahealth API credentialsBuild the project
npm run buildStart the MCP server
npm startConfigure Claude Desktop
claude mcp add athenahealth-mcp
Option 2: Use with n8n (Webhook Bridge)
If you prefer using n8n for workflow automation instead of Claude Desktop, you can use the webhook bridge:
Complete steps 1-4 above
Start the webhook bridge server
npm run webhook-bridgeThe server will start on
http://localhost:3000
(configurable viaWEBHOOK_PORT
env variable)Use in n8n workflows
In your n8n workflow, add an HTTP Request node with:
Method: GET or POST (depending on endpoint)
URL:
http://localhost:3000/[endpoint]
Authentication: None (handled by environment variables)
Body: JSON (for POST requests)
Example n8n HTTP Request nodes:
List Departments:
Method: GET URL: http://localhost:3000/departmentsSearch Patients:
Method: POST URL: http://localhost:3000/patients/search Body: { "lastname": "Smith", "firstname": "John" }Create Patient:
Method: POST URL: http://localhost:3000/patients Body: { "firstname": "John", "lastname": "Test", "dob": "05/20/1985", "sex": "M", "department_id": "1", "email": "john.test@example.com", "mobile_phone": "6179876543" }Get Clinical Summary:
Method: GET URL: http://localhost:3000/patients/134/clinical?include_allergies=true&include_prescriptions=trueView available endpoints
Navigate to
http://localhost:3000/
in your browser to see all available endpoints and their documentation.
Configuration
Environment Variables
Variable | Description | Required | Default |
| athenahealth API Client ID | Yes | - |
| athenahealth API Client Secret | Yes | - |
| athenahealth API Base URL | Yes | - |
| API Version | No |
|
| Practice ID | Yes | - |
| Webhook bridge server port (n8n mode) | No |
|
| Environment | No |
|
| Log Level | No |
|
athenahealth API Setup
Create Developer Account
Create a developer account
Request sandbox access
Create API Application
Create a new application in the developer portal
Note down your Client ID and Client Secret
Configure OAuth 2.0 settings
Get Practice ID
Contact athenahealth support to get your Practice ID
This is required for API access
MCP Tools Reference
โ Working in Sandbox (5 tools)
1. list_departments
Status: โ Fully Working Description: Lists all departments in the athenahealth practice
Parameters: None required
Example:
2. list_providers
Status: โ Fully Working Description: Lists all healthcare providers in the practice
Parameters:
name
(optional) - Filter by provider namespecialty
(optional) - Filter by specialtylimit
(optional) - Maximum results (default: 50)
Example:
3. search_patients
Status: โ Fully Working Description: Search for patients by name, DOB, phone, or email
Parameters (at least ONE required):
firstname
- Patient first namelastname
- Patient last namedob
- Date of birth (MM/DD/YYYY)phone
- Phone numberemail
- Email addresslimit
(optional) - Maximum results (default: 10)
Example:
4. create_patient
Status: โ Fully Working Description: Register a new patient in the athenahealth system
Parameters (required):
firstname
- Patient first namelastname
- Patient last namedob
- Date of birth (MM/DD/YYYY)sex
- Sex (M or F)department_id
- Primary department ID
Parameters (optional):
email
,mobile_phone
,home_phone
,address1
,city
,state
,zip
guarantor_firstname
,guarantor_lastname
,guarantor_dob
,guarantor_relationship
Important:
โ Valid North American phone numbers required (not 555 area code)
โ Date format: MM/DD/YYYY or YYYY-MM-DD
Example:
5. check_appointment_availability
Status: โ Working (returns empty in sandbox) Description: Check available appointment slots for a department and date range
Parameters:
department_id
(required) - Department IDstart_date
(required) - Start date (YYYY-MM-DD)end_date
(required) - End date (YYYY-MM-DD)provider_id
(optional) - Specific provider IDappointment_type
(optional) - Type of appointment
Note: Returns empty array in sandbox (no scheduling templates configured)
Example:
โ Not Working in Sandbox (8 tools)
These tools require production environment with full clinical access.
6. create_appointment
Status: โ Not Working - 404 Error Reason: Endpoint not available in sandbox, requires scheduling templates
7. check_drug_interactions
Status: โ Not Working - Tool Execution Failed Reason: Requires clinical endpoints and drug interaction database
8. get_clinical_summary
Status: โ Not Working - Clinical Endpoints Unavailable Reason: Clinical data endpoints (allergies, prescriptions, problems, vitals, labs, alerts) return 404
9. create_prescription
Status: โ Not Working - 404 Error Reason: E-prescribing endpoint not available in sandbox
10. get_patient_encounters
Status: โ Not Working - 404 Error Reason: Encounter endpoints not available in sandbox environment
11. get_encounter
Status: โ Not Working - 404 Error Reason: Encounter endpoints not available in sandbox environment
12. create_encounter
Status: โ Not Working - 404 Error Reason: Encounter creation requires production API with clinical documentation access
13. update_encounter
Status: โ Not Working - 404 Error Reason: Encounter endpoints not available in sandbox environment
Note: See athenahealth-mcp-tools-readme.md for detailed information on production requirements for these tools.
MCP Prompts
clinical_assessment
Generate clinical assessment prompts with patient data
Parameters:
patient_id
(required)chief_complaint
(optional)
medication_review
Generate medication review prompts (handles sandbox limitations gracefully)
Parameters:
patient_id
(required)
care_plan
Generate care plan development prompts
Parameters:
patient_id
(required)diagnosis
(optional)
Working Sample Workflow (Sandbox)
โ ๏ธ Important Notes
Sandbox vs Production
Sandbox Environment:
โ Patient registration workflows
โ Demographics and search
โ Department and provider listing
โ Appointment availability checking (returns empty)
โ Clinical data (allergies, prescriptions, problems, vitals, labs)
โ Encounter management (get, create, update)
โ Appointment creation
โ E-prescribing
โ Drug interaction checking
Production Environment: Requires:
Full athenahealth production API access
Clinical endpoints enabled (allergies, prescriptions, problems, vitals, labs, alerts)
Encounter documentation access
E-prescribing licenses and integrations
Scheduling templates configured
Provider credentials (NPI, DEA numbers)
HIPAA compliance measures
Phone Number Requirements
โ MUST use valid North American area codes (617, 212, 415, etc.)
โ CANNOT use 555 (reserved for fictional use)
Date Formats
โ MM/DD/YYYY (e.g., 05/20/1985)
โ YYYY-MM-DD (e.g., 1985-05-20)
Security and HIPAA Compliance
Data Protection
All sensitive healthcare data is automatically sanitized in logs
Patient identifiers are redacted in audit logs
API communications use form-urlencoded for POST requests
Access controls prevent unauthorized data access
Audit Logging
All data access is logged with timestamps
User actions are tracked for compliance
Failed access attempts are recorded
Audit logs are stored separately with extended retention
Best Practices
Environment Security: Store credentials in environment variables, never in code
Access Controls: Implement role-based access controls
Data Minimization: Only request necessary data
Regular Audits: Review audit logs regularly
Secure Deployment: Use secure deployment practices
API Rate Limits
athenahealth API has rate limits:
Production: 1000 requests per minute
Sandbox: 100 requests per minute
The server automatically handles rate limiting and implements exponential backoff for failed requests.
Error Handling
The server provides comprehensive error handling:
Authentication Errors: Automatic token refresh
API Errors: Structured error responses with details
Network Errors: Retry logic with exponential backoff
Validation Errors: Input validation with detailed messages
Sandbox Limitations: Graceful handling with informative error messages
Development
Running in Development Mode
Running Tests
Build Project
Architecture
The codebase is modularized for maintainability:
MCP Server Layer:
src/mcp-server.ts - Main MCP server (323 lines)
src/handlers/tool-handlers.ts - Tool implementations (635 lines)
src/handlers/prompt-handlers.ts - Prompt generators (130 lines)
src/handlers/resource-handlers.ts - Resource handlers (189 lines)
src/definitions/tools.ts - Tool schemas (226 lines)
API Client Layer (Service-Oriented):
src/services/athenahealth-client.ts - Unified client interface (130 lines)
src/services/base-client.ts - Authentication & HTTP client (220 lines)
src/services/patient-service.ts - Patient operations (130 lines)
src/services/clinical-service.ts - Clinical data (160 lines)
src/services/encounter-service.ts - Encounter management (100 lines)
src/services/scheduling-service.ts - Appointments & providers (160 lines)
Documentation
athenahealth-mcp-tools-readme.md - Complete tool reference guide
athenahealth API Documentation - Official API docs
Developer Portal - athenahealth developer resources
Support
For support and questions:
Create an issue in the GitHub repository
Review the comprehensive tool reference guide
Contact athenahealth Developer Support: developer-support@athenahealth.com
Changelog
Version 1.2.0
Added encounter management functionality (4 new tools: get_patient_encounters, get_encounter, create_encounter, update_encounter)
Refactored athenahealth client into service-oriented architecture
Separated into base-client, patient-service, clinical-service, encounter-service, scheduling-service
Reduced file sizes from 800 lines to 100-220 lines per module
Total tools increased from 9 to 13
Documented encounter endpoints return 404 in sandbox (require production)
Enhanced architecture documentation with service layer breakdown
Version 1.1.0
Refactored codebase into modular architecture
Fixed form-urlencoded POST request formatting for all endpoints
Added graceful handling of sandbox limitations
Enhanced medication_review prompt with sandbox support
Improved error messages with detailed API responses
Created comprehensive tool reference documentation
Version 1.0.0
Initial release
Basic MCP server implementation
Patient data access
Prescription management
Clinical decision support prompts
HIPAA-compliant logging
OAuth 2.0 authentication
โ ๏ธ Important: This software handles sensitive healthcare data. Ensure you comply with all applicable healthcare regulations including HIPAA, HITECH, and other relevant standards in your jurisdiction.
๐ For detailed tool specifications and production requirements, see
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
Enables AI-powered clinical decision support by integrating with athenahealth's API to access patient data, manage prescriptions, check drug interactions, and generate clinical assessments. Provides HIPAA-compliant healthcare workflows with comprehensive audit logging and data sanitization.