mcp-fresha

MCP (Model Context Protocol) server for accessing Fresha Data Connector via Snowflake. Query your Fresha business data directly through AI assistants like Claude.

Author: Boris Djordjevic

Quick Start

npm install -g mcp-fresha

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "fresha": {
      "command": "mcp-fresha",
      "env": {
        "SNOWFLAKE_ACCOUNT": "your-account.snowflakecomputing.com",
        "SNOWFLAKE_USER": "FRESHA_DATA_XXX_XXX",
        "SNOWFLAKE_PASSWORD": "your-password",
        "SNOWFLAKE_DATABASE": "FRESHA_DATA_CONNECTOR",
        "SNOWFLAKE_SCHEMA": "FRESHA_DATA_XXX",
        "SNOWFLAKE_WAREHOUSE": "FRESHA_DATA_XXX"
      }
    }
  }
}

Important: If your password contains #, wrap it in quotes: "password#123"

Get these credentials from your Fresha Data Connector settings.

Features

• Real-time Data Access: Direct connection to your Fresha business data through Snowflake
• Flexible Querying: Support for date ranges, custom filters, sorting, and pagination
• Smart Date Parsing: Natural language date inputs like "yesterday", "last week", "this month"
• Comprehensive Schema Discovery: Automatic discovery of all available tables and their structures
• Type-safe Operations: Built with TypeScript for reliability and maintainability
• Mock Mode: Development mode with sample data when Snowflake credentials are not available
• Structured Logging: Detailed logging with Pino for debugging and monitoring

Available Tools

list_fresha_reports

Lists all available tables and views in your Fresha database.

Example: "Show me all tables"

get_fresha_report

Get data from any Fresha report/table with flexible filtering options.

Parameters:

• report_name (required) - Name of the table (e.g., CASH_FLOW, SALES, BOOKINGS)
• start_date (optional) - Start date filter (YYYY-MM-DD)
• end_date (optional) - End date filter (YYYY-MM-DD)
• limit (optional) - Max records to return (default: 1000)
• order_by (optional) - Column to sort by (e.g., "SALE_DATE DESC")
• filters (optional) - Additional filters as key-value pairs

Examples:

• "Get yesterday's cash flow"
• "Show me top 10 clients by appointment count"
• "Get all bookings for this week"
• "Show sales from location 123"

Available Tables

Your Fresha database includes:

• CASH_FLOW - Transaction-level cash flow data
• BOOKINGS - Service bookings and appointments
• CLIENTS - Client information and history
• PAYMENTS - Payment transactions
• SALES - Sales records
• LOCATIONS - Business locations
• TEAM_MEMBERS - Staff information
• And more...

Troubleshooting

Authentication Failed

• Ensure credentials match exactly from Fresha Data Connector
• Check for special characters in password (especially #)
• Remove https:// from account URL if present

No Data Returned

• Verify you have the correct database and schema names
• Check Fresha Data Connector is active (8-hour daily limit)

Security

Best Practices

• Environment Variables: All sensitive credentials are stored as environment variables, never in code
• No Credential Logging: The server automatically masks Snowflake credentials in logs
• Read-Only Access: Designed for read-only operations to prevent accidental data modifications
• Input Validation: All tool inputs are validated using Zod schemas to prevent injection attacks
• Parameterized Queries: All database queries use parameterized statements to prevent SQL injection
• Session Management: Each connection is properly managed with automatic cleanup

Data Protection

• Credentials are never exposed in error messages or logs
• Mock mode prevents accidental production data access during development
• All database connections are encrypted using Snowflake's secure protocols

Development

# Clone and install
git clone https://github.com/199-biotechnologies/mcp-fresha.git
cd mcp-fresha/fresha-mcp-server
npm install

# Configure environment
cp .env.example .env
# Edit .env with your credentials

# Build and test
npm run build
npm test

# Development mode with mock data
npm run dev

# Watch mode for development
npm run watch

# Lint and type check
npm run lint
npm run typecheck

Architecture

The project follows a clean architecture pattern:

• Controllers: Business logic for handling data queries and transformations
• Services: Data access layer with Snowflake connection management
• Tools: MCP tool definitions that expose functionality to AI assistants
• Utils: Shared utilities for logging, date parsing, and error handling

Contributing

Contributions are welcome! Please ensure:

• All code passes linting (npm run lint)
• TypeScript types are properly defined
• New features include appropriate error handling
• Security best practices are followed

License

MIT