QuestLife MCP

An MCP (Model Context Protocol) server that connects your LLM (Claude, etc.) to a QuestLife Supabase backend — letting you manage quests, habits, XP, and levels through natural language.

What is QuestLife?

QuestLife is a personal gamification system where you track life goals as RPG-style quests and build habits that earn XP. This MCP server acts as the bridge between any MCP-compatible LLM and your QuestLife Supabase database.

Features

• 15 tools covering quests, habits, progress, and overview
• Full CRUD for quests and habits
• XP + level system with automatic calculation
• Streak tracking with weekly bonus (+50 XP every 7 consecutive days)
• Real-time sync with the QuestLife web app (same Supabase backend)
• Works with Claude Desktop, Claude Code, and any MCP-compatible client

Tools Reference

Quests

| Tool | Description | |------|-------------| | list_quests | List quests with optional filters: status, category, act | | get_quest | Get a single quest by ID | | create_quest | Create a new quest with title, description, XP reward, subtasks | | update_quest | Update any quest field | | delete_quest | Permanently delete a quest |

Habits

| Tool | Description | |------|-------------| | list_habits | List all habits | | get_habit | Get a single habit by ID | | create_habit | Create a habit with frequency, XP per day, category | | update_habit | Update any habit field | | delete_habit | Permanently delete a habit |

Progress

| Tool | Description | |------|-------------| | complete_quest | Mark quest as completed and award XP | | set_quest_status | Change quest status (locked, in_progress, completed) | | toggle_habit_today | Mark/unmark habit completion for today, updates streak and XP | | toggle_subtask | Toggle a subtask inside a quest or habit |

Overview

| Tool | Description | |------|-------------| | list_all | Full snapshot: profile, quest summary, and all habits with today's status |

Prerequisites

1. A Supabase project with the QuestLife schema
2. Node.js >= 18
3. A QuestLife user ID (UUID from the profiles table)

Required Supabase Tables

-- profiles: user XP and level
-- quests:   user_id, quest_id, data (JSONB), updated_at
-- habits:   user_id, habit_id, data (JSONB), updated_at
-- xp_log:   user_id, date, amount, reason, created_at

Installation

Option A — npx (no install required)

npx questlife-mcp

Option B — global install

npm install -g questlife-mcp
questlife-mcp

Option C — from source

git clone https://github.com/jaara/questlife-mcp.git
cd questlife-mcp
npm install
npm run build

Configuration

Create a .env file (copy from .env.example):

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-role-key-here
QUESTLIFE_USER_ID=your-user-uuid-here

Security note: The SUPABASE_SERVICE_KEY is a service role key that bypasses Row Level Security. Keep it secret and never commit it to version control.

Usage with Claude Desktop

Add the following to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Using npx (recommended)

{
  "mcpServers": {
    "questlife": {
      "command": "npx",
      "args": ["questlife-mcp"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-role-key",
        "QUESTLIFE_USER_ID": "your-user-uuid"
      }
    }
  }
}

Using a local build

{
  "mcpServers": {
    "questlife": {
      "command": "node",
      "args": ["/absolute/path/to/questlife-mcp/dist/index.js"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-role-key",
        "QUESTLIFE_USER_ID": "your-user-uuid"
      }
    }
  }
}

Restart Claude Desktop after saving the config.

Usage with Claude Code

Add this to your project's .mcp.json or global MCP config:

{
  "mcpServers": {
    "questlife": {
      "command": "npx",
      "args": ["questlife-mcp"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-role-key",
        "QUESTLIFE_USER_ID": "your-user-uuid"
      }
    }
  }
}

Example Prompts

Once connected to Claude, you can use natural language:

"Show me all my in-progress quests"
"Create a new quest called 'Learn Rust' with 500 XP reward"
"Mark the quest 'Build portfolio' as completed"
"I completed my meditation habit today"
"What's my current level and XP?"
"Give me a full overview of my quests and habits"
"Add a daily coding habit worth 100 XP per day"

Data Model

Quest

{
  id: string;           // UUID
  title: string;
  description: string;
  category: string;
  act: number;          // Story act / chapter
  status: 'locked' | 'in_progress' | 'completed';
  xpReward: number;
  subtasks: { id: string; title: string; completed: boolean }[];
  createdAt: string;    // ISO 8601
  completedAt: string | null;
}

Habit

{
  id: string;           // UUID
  title: string;
  description: string;
  category: string;
  xpPerDay: number;
  frequency: 'daily' | 'weekly';
  streak: number;       // Consecutive days completed
  checkHistory: { [date: string]: boolean };  // "YYYY-MM-DD" keys
  createdAt: string;
}

XP & Level Formula

Level N requires:  N * (N+1) / 2 * 500  cumulative XP

| Level | Total XP required | |-------|-------------------| | 1 | 500 | | 2 | 1,500 | | 3 | 3,000 | | 5 | 7,500 | | 10 | 27,500 |

Development

# Install dependencies
npm install

# Run in development mode (no build step)
npm run dev

# Build TypeScript
npm run build

# Run compiled version
npm start

Contributing

Issues and pull requests are welcome. Please open an issue first to discuss significant changes.

License

MIT — see LICENSE