athenahealth MCP Server

# 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 the author: Gboyega Ofi at [gboyega.ofi@gmail.com](mailto: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](LICENSE) file for details. Copyright (c) 2025 Gboyega Ofi ([gboyega.ofi@gmail.com](mailto: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](athenahealth-mcp-tools-readme.md)**