README.md•8.6 kB
# 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
## 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:
```bash
pip install aiohttp python-dotenv mcp
```
2. Set environment variables:
```bash
export ATHENA_CLIENT_ID='your_client_id'
export ATHENA_CLIENT_SECRET='your_client_secret'
export ATHENA_PRACTICE_ID='your_practice_id'
export ATHENA_BASE_URL='https://api.athenahealth.com' # Optional
```
3. Run the server:
```bash
python main.py
```
## 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:**
```json
{
"start_date": "2024-01-01",
"end_date": "2024-01-31",
"provider_id": "12345"
}
```
### 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:**
```json
{
"provider_id": "12345",
"department_id": "67890",
"appointment_type_id": "11111",
"start_date": "2024-01-01",
"end_date": "2024-01-31"
}
```
### 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:**
```json
{
"patient_id": "99999",
"provider_id": "12345",
"department_id": "67890",
"appointment_type_id": "11111",
"appointment_date": "2024-01-15",
"appointment_time": "14:30",
"reason_for_visit": "Annual checkup"
}
```
### 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:**
```json
{
"appointment_id": "55555",
"appointment_date": "2024-01-16",
"appointment_time": "15:00",
"reason_for_visit": "Follow-up appointment",
"notes": "Patient requested time change"
}
```
### 5. cancel_appointment
Cancel an appointment.
**Parameters:**
- `appointment_id` (required): Appointment ID to cancel
- `cancellation_reason` (optional): Reason for cancellation
**Example:**
```json
{
"appointment_id": "55555",
"cancellation_reason": "Patient requested cancellation"
}
```
### 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:**
```json
{
"department_id": "67890",
"specialty": "Cardiology"
}
```
### 7. get_departments
Get list of all departments.
**Parameters:**
None
**Example:**
```json
{}
```
### 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:**
```json
{
"department_id": "67890",
"provider_id": "12345"
}
```
### 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:**
```json
{
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-01-01"
}
```
## 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:**
```json
{"tool": "get_departments", "arguments": {}}
```
2. **Get providers in a department:**
```json
{"tool": "get_providers", "arguments": {"department_id": "67890"}}
```
3. **Get appointment types:**
```json
{"tool": "get_appointment_types", "arguments": {"department_id": "67890"}}
```
4. **Search for available slots:**
```json
{
"tool": "get_available_slots",
"arguments": {
"provider_id": "12345",
"department_id": "67890",
"appointment_type_id": "11111",
"start_date": "2024-01-01",
"end_date": "2024-01-31"
}
}
```
5. **Search for a patient:**
```json
{
"tool": "search_patients",
"arguments": {
"first_name": "John",
"last_name": "Doe"
}
}
```
6. **Create an appointment:**
```json
{
"tool": "create_appointment",
"arguments": {
"patient_id": "99999",
"provider_id": "12345",
"department_id": "67890",
"appointment_type_id": "11111",
"appointment_date": "2024-01-15",
"appointment_time": "14:30",
"reason_for_visit": "Annual checkup"
}
}
```
## Response Format
All tool responses are returned as JSON strings containing the API response data. For example:
```json
{
"appointments": [
{
"appointmentid": "55555",
"patientid": "99999",
"providerid": "12345",
"departmentid": "67890",
"appointmentdate": "2024-01-15",
"appointmenttime": "14:30",
"appointmenttype": "Annual Checkup",
"status": "scheduled"
}
]
}
```
## 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