Athena Health MCP Server

A Model Context Protocol (MCP) server for integrating with Athena Health's API to manage appointments, providers, departments, and patient data.

Overview

This MCP server provides tools for:

• Appointment management (create, update, cancel, view)

• Provider and department information

• Patient search functionality

• Available appointment slot discovery

Related MCP server: MCP Server for Asana

Setup

Prerequisites

1. Python 3.8+

2. Required environment variables:

   • ATHENA_CLIENT_ID: Your Athena Health API client ID

   • ATHENA_CLIENT_SECRET: Your Athena Health API client secret

   • ATHENA_PRACTICE_ID: Your practice ID

   • ATHENA_BASE_URL: (Optional) API base URL (defaults to production)

Installation

1. Install dependencies:

2. Set environment variables:

3. Run the server:

Available Tools

1. get_appointments

Retrieve appointments for a specific date range with optional filtering.

Parameters:

• start_date (required): Start date in YYYY-MM-DD format

• end_date (required): End date in YYYY-MM-DD format

• provider_id (optional): Provider ID to filter appointments

• department_id (optional): Department ID to filter appointments

Example:

2. get_available_slots

Get available appointment slots for scheduling.

Parameters:

• provider_id (required): Provider ID

• department_id (required): Department ID

• appointment_type_id (required): Appointment type ID

• start_date (required): Start date in YYYY-MM-DD format

• end_date (required): End date in YYYY-MM-DD format

Example:

3. create_appointment

Create a new appointment.

Parameters:

• patient_id (required): Patient ID

• provider_id (required): Provider ID

• department_id (required): Department ID

• appointment_type_id (required): Appointment type ID

• appointment_date (required): Appointment date in YYYY-MM-DD format

• appointment_time (required): Appointment time in HH:MM format

• reason_for_visit (optional): Reason for the visit

Example:

4. update_appointment

Update an existing appointment.

Parameters:

• appointment_id (required): Appointment ID to update

• appointment_date (optional): New appointment date in YYYY-MM-DD format

• appointment_time (optional): New appointment time in HH:MM format

• reason_for_visit (optional): Updated reason for the visit

• notes (optional): Additional notes

Example:

5. cancel_appointment

Cancel an appointment.

Parameters:

• appointment_id (required): Appointment ID to cancel

• cancellation_reason (optional): Reason for cancellation

Example:

6. get_providers

Get list of providers with optional filtering.

Parameters:

• department_id (optional): Department ID to filter providers

• specialty (optional): Specialty to filter providers

Example:

7. get_departments

Get list of all departments.

Parameters: None

Example:

8. get_appointment_types

Get available appointment types with optional filtering.

Parameters:

• department_id (optional): Department ID to filter appointment types

• provider_id (optional): Provider ID to filter appointment types

Example:

9. search_patients

Search for patients by various criteria.

Parameters:

• first_name (optional): Patient first name

• last_name (optional): Patient last name

• date_of_birth (optional): Date of birth in YYYY-MM-DD format

• phone (optional): Phone number

• email (optional): Email address

Example:

API Endpoints

The server interacts with the following Athena Health API endpoints:

• POST /oauth2/v1/token - Authentication

• GET /v1/{practice_id}/appointments - Get appointments

• GET /v1/{practice_id}/appointments/open - Get available slots

• POST /v1/{practice_id}/appointments - Create appointment

• PUT /v1/{practice_id}/appointments/{id} - Update appointment

• GET /v1/{practice_id}/providers - Get providers

• GET /v1/{practice_id}/departments - Get departments

• GET /v1/{practice_id}/appointmenttypes - Get appointment types

• GET /v1/{practice_id}/patients - Search patients

Authentication

The server automatically handles OAuth2 authentication using client credentials flow. Tokens are cached and refreshed as needed.

Error Handling

The server includes comprehensive error handling for:

• Authentication failures

• API request failures

• Invalid parameters

• Network errors

All errors are logged and returned as part of the tool response.

Usage Examples

Complete Workflow Example

1. Get departments:

2. Get providers in a department:

3. Get appointment types:

4. Search for available slots:

5. Search for a patient:

6. Create an appointment:

Response Format

All tool responses are returned as JSON strings containing the API response data. For example:

Troubleshooting

Common Issues

1. Authentication Errors:

   • Verify your ATHENA_CLIENT_ID and ATHENA_CLIENT_SECRET are correct

   • Ensure your API credentials have the necessary permissions

2. Missing Environment Variables:

   • The server will exit with an error message listing missing variables

   • Set all required environment variables before running

3. API Request Failures:

   • Check that your ATHENA_PRACTICE_ID is correct

   • Verify the API endpoints are accessible from your network

   • Review the error response for specific API error messages

Logging

The server logs all operations at INFO level. Check the console output for detailed information about:

• Authentication attempts

• API requests and responses

• Error details

Security Considerations

• Never commit API credentials to version control

• Use environment variables for all sensitive configuration

• The server automatically handles token refresh and secure storage

• All API communication uses HTTPS

Support

For issues with the MCP server implementation, check the logs for detailed error messages. For Athena Health API-specific issues, refer to the official Athena Health API documentation. # athenahealth-mcp