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-server -
Install dependencies
npm install -
Configure environment variables
cp config/environment.example .env # Edit .env with your athenahealth API credentials -
Build the project
npm run build -
Start the MCP server
npm start -
Configure 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_PORTenv 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=true -
View 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 |
|---|---|---|---|
ATHENA_CLIENT_ID | athenahealth API Client ID | Yes | - |
ATHENA_CLIENT_SECRET | athenahealth API Client Secret | Yes | - |
ATHENA_BASE_URL | athenahealth API Base URL | Yes | - |
ATHENA_VERSION | API Version | No | v1 |
ATHENA_PRACTICE_ID | Practice ID | Yes | - |
WEBHOOK_PORT | Webhook bridge server port (n8n mode) | No | 3000 |
NODE_ENV | Environment | No | development |
LOG_LEVEL | Log Level | No | info |
athenahealth API Setup
-
Create Developer Account
- Visit athenahealth Developer Portal
- 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:
// List all departments
const departments = await mcpClient.callTool('list_departments', {});
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:
// List all providers
const providers = await mcpClient.callTool('list_providers', {
specialty: 'Cardiology',
limit: 20
});
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:
// Search for patients by name
const patients = await mcpClient.callTool('search_patients', {
firstname: 'John',
lastname: 'Smith',
limit: 10
});
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,zipguarantor_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:
const patient = await mcpClient.callTool('create_patient', {
firstname: 'John',
lastname: 'Test',
dob: '05/20/1985',
sex: 'M',
department_id: '1',
email: 'john.test@example.com',
mobile_phone: '6179876543',
address1: '123 Main St',
city: 'Boston',
state: 'MA',
zip: '02101'
});
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:
const availability = await mcpClient.callTool('check_appointment_availability', {
department_id: '1',
start_date: '2025-11-01',
end_date: '2025-11-07',
provider_id: '23'
});
❌ 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)
// Step 1: List departments
const departments = await mcpClient.callTool('list_departments', {});
const departmentId = departments[0].departmentid;
// Step 2: Create a test patient
const patient = await mcpClient.callTool('create_patient', {
firstname: 'John',
lastname: 'Test',
dob: '05/20/1985',
sex: 'M',
department_id: departmentId,
email: 'john.test@example.com',
mobile_phone: '6179876543',
address1: '123 Main St',
city: 'Boston',
state: 'MA',
zip: '02101'
});
// Returns: { patientid: "61378" }
// Step 3: Search for the patient
const searchResults = await mcpClient.callTool('search_patients', {
lastname: 'Test',
dob: '05/20/1985'
});
// Step 4: List providers
const providers = await mcpClient.callTool('list_providers', {
specialty: 'Family Medicine'
});
⚠️ 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
npm run dev
Running Tests
npm test
Build Project
npm run build
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 the author: Gboyega Ofi at gboyega.ofi@gmail.com
- 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
License
MIT License - see LICENSE file for details.
Copyright (c) 2025 Gboyega Ofi (gboyega.ofi@gmail.com)
⚠️ 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 athenahealth-mcp-tools-readme.md