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-bridge
```
The server will start on http://localhost:3000 (configurable via WEBHOOK_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/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

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 name
specialty (optional) - Filter by specialty
limit (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 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:

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

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:

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.

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

athenahealth MCP Server

📊 Tool Status Overview

Features

🏥 Clinical Decision Support

🔒 HIPAA Compliance

🚀 AI-Powered Workflows

Installation

Prerequisites

Quick Start

Option 1: Use with Claude Desktop (MCP)

Option 2: Use with n8n (Webhook Bridge)

Configuration

Environment Variables

athenahealth API Setup

MCP Tools Reference

✅ Working in Sandbox (5 tools)

1. list_departments

2. list_providers

3. search_patients

4. create_patient

5. check_appointment_availability

❌ Not Working in Sandbox (8 tools)

6. create_appointment

7. check_drug_interactions

8. get_clinical_summary

9. create_prescription

10. get_patient_encounters

11. get_encounter

12. create_encounter

13. update_encounter

MCP Prompts

clinical_assessment

medication_review

care_plan

Working Sample Workflow (Sandbox)

⚠️ Important Notes

Sandbox vs Production

Phone Number Requirements

Date Formats

Security and HIPAA Compliance

Data Protection

Audit Logging

Best Practices

API Rate Limits

Error Handling

Development

Running in Development Mode

Running Tests

Build Project

Architecture

Documentation

Support

Changelog

Version 1.2.0

Version 1.1.0

Version 1.0.0

License

Reviews