README.md•17 kB
# 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)
1. **Clone the repository**
```bash
git clone https://github.com/ophydami/athenahealth-mcp-server.git
cd athenahealth-mcp-server
```
2. **Install dependencies**
```bash
npm install
```
3. **Configure environment variables**
```bash
cp config/environment.example .env
# Edit .env with your athenahealth API credentials
```
4. **Build the project**
```bash
npm run build
```
5. **Start the MCP server**
```bash
npm start
```
6. **Configure Claude Desktop**
```bash
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:
1. **Complete steps 1-4 above**
2. **Start the webhook bridge server**
```bash
npm run webhook-bridge
```
The server will start on `http://localhost:3000` (configurable via `WEBHOOK_PORT` env variable)
3. **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/departments
```
**Search 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
```
4. **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
1. **Create Developer Account**
- Visit [athenahealth Developer Portal](https://www.athenahealth.com/developer-portal)
- Create a developer account
- Request sandbox access
2. **Create API Application**
- Create a new application in the developer portal
- Note down your Client ID and Client Secret
- Configure OAuth 2.0 settings
3. **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:**
```typescript
// 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 name
- `specialty` (optional) - Filter by specialty
- `limit` (optional) - Maximum results (default: 50)
**Example:**
```typescript
// 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 name
- `lastname` - Patient last name
- `dob` - Date of birth (MM/DD/YYYY)
- `phone` - Phone number
- `email` - Email address
- `limit` (optional) - Maximum results (default: 10)
**Example:**
```typescript
// 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 name
- `lastname` - Patient last name
- `dob` - 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:**
```typescript
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 ID
- `start_date` (required) - Start date (YYYY-MM-DD)
- `end_date` (required) - End date (YYYY-MM-DD)
- `provider_id` (optional) - Specific provider ID
- `appointment_type` (optional) - Type of appointment
**Note:** Returns empty array in sandbox (no scheduling templates configured)
**Example:**
```typescript
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](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)
```typescript
// 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
1. **Environment Security**: Store credentials in environment variables, never in code
2. **Access Controls**: Implement role-based access controls
3. **Data Minimization**: Only request necessary data
4. **Regular Audits**: Review audit logs regularly
5. **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
```bash
npm run dev
```
### Running Tests
```bash
npm test
```
### Build Project
```bash
npm run build
```
---
## Architecture
The codebase is modularized for maintainability:
**MCP Server Layer:**
- **[src/mcp-server.ts](src/mcp-server.ts)** - Main MCP server (323 lines)
- **[src/handlers/tool-handlers.ts](src/handlers/tool-handlers.ts)** - Tool implementations (635 lines)
- **[src/handlers/prompt-handlers.ts](src/handlers/prompt-handlers.ts)** - Prompt generators (130 lines)
- **[src/handlers/resource-handlers.ts](src/handlers/resource-handlers.ts)** - Resource handlers (189 lines)
- **[src/definitions/tools.ts](src/definitions/tools.ts)** - Tool schemas (226 lines)
**API Client Layer (Service-Oriented):**
- **[src/services/athenahealth-client.ts](src/services/athenahealth-client.ts)** - Unified client interface (130 lines)
- **[src/services/base-client.ts](src/services/base-client.ts)** - Authentication & HTTP client (220 lines)
- **[src/services/patient-service.ts](src/services/patient-service.ts)** - Patient operations (130 lines)
- **[src/services/clinical-service.ts](src/services/clinical-service.ts)** - Clinical data (160 lines)
- **[src/services/encounter-service.ts](src/services/encounter-service.ts)** - Encounter management (100 lines)
- **[src/services/scheduling-service.ts](src/services/scheduling-service.ts)** - Appointments & providers (160 lines)
---
## Documentation
- **[athenahealth-mcp-tools-readme.md](athenahealth-mcp-tools-readme.md)** - Complete tool reference guide
- **[athenahealth API Documentation](https://docs.athenahealth.com/)** - Official API docs
- **[Developer Portal](https://developer.athenahealth.com/)** - athenahealth developer resources
---
## Support
For support and questions:
- Create an issue in the GitHub repository
- Review the comprehensive [tool reference guide](athenahealth-mcp-tools-readme.md)
- 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 [athenahealth-mcp-tools-readme.md](athenahealth-mcp-tools-readme.md)**