apphud-mcp

MCP server for Apphud dashboard analytics endpoints (apps, events, metrics, cohorts).

Quick Start

1. Add MCP server:

{
  "mcpServers": {
    "apphud-mcp": {
      "command": "npx",
      "args": ["-y", "[email protected]", "start"],
      "env": {
        "login": "[email protected]",
        "password": "your_apphud_password"
      }
    }
  }
}

2. Restart MCP server.
3. Check dashboard access:
   • apphud_apps_list
   • apphud_analytics_events_list (requires from/to)
   • apphud_analytics_metric_timeseries (requires metric_key, from, to)

HTTP Tool Calls

If HTTP_ENABLED=true, you can call tools over HTTP (stable payload path for web clients):

curl -sS -X POST http://localhost:8080/tools/call \
  -H 'content-type: application/json' \
  -d '{
    "name":"apphud_analytics_metric_timeseries",
    "arguments":{
      "app_id":"your_app_id",
      "metric_key":"revenue_gross",
      "from":"2026-02-01T00:00:00.000Z",
      "to":"2026-02-21T23:59:59.000Z"
    }
  }'

The endpoint also accepts toolName and stringified arguments JSON for compatibility with buggy wrappers.

ETL Setup

1. In Apphud:
   • Open Integrations -> GCS ETL -> Add connection.
   • Enter project/service account/bucket and enable export for apps.
2. In Google Cloud Console:
   • Create/select a bucket in Cloud Storage.
   • Create a Service Account in IAM.
   • Create JSON key for that service account.
   • Grant access to the bucket (read for MCP side, write for Apphud side as needed by your policy).
3. MCP env vars:
   • ETL_SOURCE=gcs
   • ETL_GCS_BUCKET=<bucket-name>
   • ETL_GCS_PREFIX=<optional-prefix>
   • GOOGLE_APPLICATION_CREDENTIALS=<path-to-service-account-json>
4. Ensure gsutil is installed and authenticated in runtime environment.

1. In Apphud:
   • Open Integrations -> S3 ETL -> Add connection.
   • Fill bucket/credentials/region and enable export for apps.
2. In AWS Console:
   • Create/select bucket in S3.
   • Create IAM user/role with bucket access.
   • Generate access key (if using user credentials).
3. MCP env vars:
   • ETL_SOURCE=s3
   • ETL_S3_BUCKET=<bucket-name>
   • ETL_S3_PREFIX=<optional-prefix>
   • AWS_ACCESS_KEY_ID=<key-id>
   • AWS_SECRET_ACCESS_KEY=<secret>
   • AWS_REGION=<region>
4. Ensure AWS CLI (aws) is installed and usable in runtime environment.

Defaults

• SQLite DB: .apphud-mcp/apphud.db
• Incoming ETL files: .apphud-etl/incoming
• Poll interval: 60 minutes
• ETL enabled: true
• ETL source default: none (set ETL_SOURCE=gcs or ETL_SOURCE=s3)

Useful Tools

• apphud_apps_list
• apphud_analytics_events_list
• apphud_analytics_metrics_list
• apphud_analytics_metric_value
• apphud_analytics_metric_timeseries
• apphud_analytics_metric_breakdown
• apphud_analytics_revenue_summary
• apphud_analytics_subscriptions_summary
• apphud_analytics_conversion_trial_to_paid
• apphud_analytics_cohorts_retention
• apphud_analytics_cohorts_ltv
• apphud_analytics_query_raw

Development

npm install
npm run ci