freemius-mcp

Minimal standalone MCP server for Freemius product data over stdio.

It exposes exactly three tools:

• list_sites
• list_subscriptions
• list_event_logs

This server is not tied to any single product or app. You can set a default FREEMIUS_PRODUCT_ID for convenience, then override product_id per tool call to use the same server across multiple Freemius products.

Requirements

• Node.js 20+
• A Freemius bearer token

Install

npm install

Environment Variables

Required:

• FREEMIUS_BEARER_TOKEN

Optional:

• FREEMIUS_PRODUCT_ID
  • Default product ID used when a tool call does not include product_id
• FREEMIUS_API_BASE
  • Defaults to https://api.freemius.com/v1

Example:

export FREEMIUS_BEARER_TOKEN=your_token_here
export FREEMIUS_PRODUCT_ID=1234

Run

Build:

npm run build

Start the stdio MCP server:

npm start

For local development:

npm run dev

MCP Client Configuration

Codex-style example:

{
  "mcpServers": {
    "freemius": {
      "command": "node",
      "args": ["/absolute/path/to/freemius-mcp/dist/server.js"],
      "env": {
        "FREEMIUS_BEARER_TOKEN": "your_token_here",
        "FREEMIUS_PRODUCT_ID": "1234"
      }
    }
  }
}

Claude Desktop-style example:

{
  "mcpServers": {
    "freemius": {
      "command": "node",
      "args": ["/absolute/path/to/freemius-mcp/dist/server.js"],
      "env": {
        "FREEMIUS_BEARER_TOKEN": "your_token_here",
        "FREEMIUS_PRODUCT_ID": "1234"
      }
    }
  }
}

Tools

list_sites

Lists installs for a Freemius product.

Arguments:

• product_id optional string
• count optional integer, 1..50
• offset optional integer, >= 0
• search optional string
• is_active optional boolean
• plan_id optional positive integer
• fields optional comma-separated string

Example call:

{
  "name": "list_sites",
  "arguments": {
    "count": 10,
    "is_active": true
  }
}

Cross-product example:

{
  "name": "list_sites",
  "arguments": {
    "product_id": "9876",
    "count": 5
  }
}

list_subscriptions

Lists subscriptions for a Freemius product.

Arguments:

• product_id optional string
• count optional integer, 1..50
• offset optional integer, >= 0
• search optional string
• filter optional enum: all, active, cancelled
• billing_cycle optional enum: 0, 1, 12
• gateway optional enum: paypal, stripe
• plan_id optional positive integer
• fields optional comma-separated string

Example call:

{
  "name": "list_subscriptions",
  "arguments": {
    "filter": "active",
    "billing_cycle": 12,
    "count": 10
  }
}

list_event_logs

Lists event logs for either an install or a user.

Arguments:

• product_id optional string
• install_id optional positive integer
• user_id optional positive integer
• count optional integer, 1..50
• offset optional integer, >= 0
• fields optional comma-separated string

Validation:

• Provide exactly one of install_id or user_id

Example call by install:

{
  "name": "list_event_logs",
  "arguments": {
    "install_id": 4321,
    "count": 20
  }
}

Example call by user with a product override:

{
  "name": "list_event_logs",
  "arguments": {
    "product_id": "9876",
    "user_id": 2468,
    "offset": 20
  }
}

Testing

npm test

The tests cover:

• default product ID usage
• per-call product_id overrides
• event log endpoint selection
• validation failures
• Freemius API error handling

Notes

• If FREEMIUS_PRODUCT_ID is unset, each tool call must include product_id
• This server is designed for reuse across multiple Freemius products from one MCP server instance

Sources

• Freemius installation listing docs: https://docs.freemius.com/api/installations/list-installs
• Freemius subscriptions docs: https://docs.freemius.com/api/subscriptions