@getaiva/mcp

v0.1.0

Published

4 months ago

Model Context Protocol server for AIVA - Connect AI tools to customer intelligence and Shopify data

0High
0Medium
0Low

getaiva

mcp model-context-protocol aiva shopify ai claude cursor subscriptions ecommerce

AIVA MCP Server

Model Context Protocol server for AIVA - Connect your AI coding tools to AIVA's customer intelligence and Shopify data.

What is this?

AIVA MCP is a Model Context Protocol server that gives AI coding assistants (Claude, Cursor, Windsurf, etc.) direct access to:

Customer Intelligence - RFM segments, health scores, churn predictions
Subscription Data - Active subscriptions, delivery schedules, lifecycle events
Affiliate Tracking - Referral codes, commissions, leaderboards
Shopify Store Data - Products, orders, customers (proxied through AIVA)

Quick Start

Installation

npm install @getaiva/mcp

Configuration

Add to your MCP configuration file:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "aiva": {
      "command": "npx",
      "args": ["@getaiva/mcp"],
      "env": {
        "AIVA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor (.cursor/mcp.json in your project):

{
  "mcpServers": {
    "aiva": {
      "command": "npx",
      "args": ["@getaiva/mcp"],
      "env": {
        "AIVA_API_KEY": "your-api-key-here"
      }
    }
  }
}

VS Code with Continue (.continue/config.json):

{
  "mcpServers": [
    {
      "name": "aiva",
      "command": "npx",
      "args": ["@getaiva/mcp"],
      "env": {
        "AIVA_API_KEY": "your-api-key-here"
      }
    }
  ]
}

Getting Your API Key

Log in to your AIVA Merchant Dashboard
Go to Settings > API Keys
Create a new API key with the scopes you need
Copy the key and add it to your MCP configuration

Available Tools

Once connected, your AI assistant can use these tools:

Customer Intelligence

| Tool | Description | |------|-------------| | aiva_get_customer | Get customer profile by ID or email | | aiva_search_customers | Search customers with filters | | aiva_get_rfm_segments | Get RFM segment breakdown | | aiva_get_churn_risk | Get customers at risk of churning |

Subscriptions

| Tool | Description | |------|-------------| | aiva_get_subscription | Get subscription details | | aiva_list_subscriptions | List subscriptions with filters | | aiva_get_delivery_schedule | Get upcoming deliveries | | aiva_subscription_actions | Pause, resume, skip, swap products |

Affiliates

| Tool | Description | |------|-------------| | aiva_get_affiliate | Get affiliate details | | aiva_list_affiliates | List affiliates with stats | | aiva_get_referrals | Get referral history |

Shopify (Proxied)

| Tool | Description | |------|-------------| | shopify_get_products | Search/list products | | shopify_get_product | Get product by ID | | shopify_get_orders | List orders | | shopify_get_customer | Get Shopify customer |

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | AIVA_API_KEY | Yes | Your AIVA API key | | AIVA_API_URL | No | Custom API URL (default: https://api.aiva.io) | | SHOPIFY_ACCESS_TOKEN | No | Direct Shopify access (bypasses proxy) | | SHOPIFY_STORE | No | Your Shopify store domain |

Example Usage

Once configured, ask your AI assistant things like:

"Show me customers at high risk of churning"

"Get the subscription details for customer [email protected]"

"List all products in the 'dog-food' collection"

"What are our top-performing affiliates this month?"

"Find customers in the 'Champions' RFM segment"

Development

Running Locally

git clone https://github.com/0800tim/aiva-mcp.git
cd aiva-mcp
npm install
npm run dev

Testing

npm test

Building

npm run build

Troubleshooting

"AIVA_API_KEY not configured"

Make sure your API key is set in the env section of your MCP configuration.

"Connection refused"

Check that:

Your API key is valid
You have network access to the AIVA API
The MCP server started correctly

Debug Mode

Set DEBUG=aiva:* environment variable for verbose logging:

{
  "env": {
    "AIVA_API_KEY": "your-key",
    "DEBUG": "aiva:*"
  }
}