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

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

   git clone https://github.com/ophydami/athenahealth-mcp-server.git cd athenahealth-mcp-server

2. Install dependencies

   npm install

3. Configure environment variables

   cp config/environment.example .env # Edit .env with your athenahealth API credentials

4. Build the project

   npm run build

5. Start the MCP server

   npm start

6. 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:

1. Complete steps 1-4 above

2. Start the webhook bridge server

   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

athenahealth API Setup

1. Create Developer Account

   • Visit athenahealth 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:

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:

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:

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:

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:

❌ 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

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

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 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