🎁

Gift Calculator

The only hackable open source gift calculation tool you´ll ever need

🚀 Interactive Demo

Try gift-calc right in your browser! No installation required.

Type commands directly in the terminal below - it works just like the real CLI.

gift-calc interactive terminal

Installation

🍺 Homebrew

macOS & Linux

$ brew tap gift-calc/homebrew-gift-calc && brew install gift-calc

📦 NPM

All platforms

$ npm install -g gift-calc

🚀 Install Script

Unix/Linux/macOS

$ curl -fsSL https://raw.githubusercontent.com/gift-calc/gift-calc/main/install.sh | sh

🐳 Docker

All platforms

$ docker run --rm gift-calc/gift-calc --help

🪟 PowerShell

Windows

> irm https://raw.githubusercontent.com/gift-calc/gift-calc/main/install.ps1 | iex

Features

🎯

Smart Calculations

Configurable base amounts with intelligent random variation

👥

Relationship Bias

Friend scores influence amounts based on relationship closeness

😊

Personality Scoring

Nice scores affect gift amounts with special cases for mean people

💳

Budget Management

Set spending budgets for specific periods and track your gift expenses

🎅

Naughty List

Manage a naughty list to ensure certain people receive minimal gifts

⚙️

Persistent Config

Save your preferences and update them anytime

📝

Automatic Logging

Track all calculations with timestamps and recipients

💰

Multiple Currencies

Support for any currency with customizable decimal places

🔌 AI Assistant Integration

Connect gift-calc directly to AI assistants like Claude, GPT, and more using the Model Context Protocol (MCP). Get intelligent gift calculations through natural conversation.

⚡

Seamless Integration

Use gift-calc directly within AI conversations

🔄

Real-time Interaction

AI assistants access your live config and data

🌍

Universal Protocol

Works with any MCP-compatible AI client

Client Setup

Choose your AI client to see setup instructions

Claude Desktop Setup

1
Install gift-calc
$ npm install -g gift-calc
2
Configure Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json 
{
  "mcpServers": {
    "gift-calc": {
      "command": "gift-calc-mcp",
      "args": [],
      "env": {}
    }
  }
}
3
Restart & Test

Restart Claude Desktop and look for the MCP connection indicator (🔌). Test with: "Calculate a gift amount for Alice"

Claude Code Setup

1
Install gift-calc
$ npm install -g gift-calc
2
Add MCP Server
$ claude mcp add gift-calc gift-calc-mcp
3
Verify Installation
$ claude mcp list

VS Code Setup

1
Install gift-calc
$ npm install -g gift-calc
2
Create Workspace Configuration

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "gift-calc": {
      "type": "stdio",
      "command": "gift-calc-mcp"
    }
  }
}

Cursor IDE Setup

1
Install gift-calc & Configure
$ npm install -g gift-calc

Add to Cursor Composer configuration:

{
  "mcp": {
    "servers": {
      "gift-calc": {
        "command": "gift-calc-mcp"
      }
    }
  }
}

Zed Editor Setup

1
Install & Configure Zed
$ npm install -g gift-calc

Add to Zed settings.json:

{
  "context_servers": {
    "gift-calc": {
      "source": "custom",
      "command": "gift-calc-mcp",
      "args": [],
      "env": {}
    }
  }
}

Continue (VS Code/JetBrains) Setup

1
Install & Configure Continue
$ npm install -g gift-calc

Add to Continue's MCP configuration:

{
  "mcpServers": {
    "gift-calc": {
      "command": "gift-calc-mcp"
    }
  }
}

LM Studio Setup

1
Install & Configure LM Studio
$ npm install -g gift-calc

Add to mcp.json configuration file:

{
  "servers": {
    "gift-calc": {
      "command": "gift-calc-mcp"
    }
  }
}

Generic MCP Client Setup

1
Requirements

For any MCP-compatible client that supports STDIO transport:

  • Command: gift-calc-mcp
  • Transport: STDIO
  • Protocol Version: 2025-06-18
  • Arguments: None required
$ npm install -g gift-calc

Available Tools

Safe Tools Read-Only

🎁
Calculate Gift Amount

Smart calculations with friend & nice scores

🔍
Match Previous Gift

Find and match gift history

📊
Get Budget Status

View spending and remaining budget

⚙️
Get Configuration

View current settings and defaults

Management Tools Requires Confirmation

🎅
Naughty List

Add/remove people from naughty list

💰
Set Budget

Create spending budgets with dates

🔧
Initialize Config

Set up default values and preferences

AI Integration Examples

You

"I need to calculate a gift for my coworker Sarah. I usually spend around 75 SEK on coworkers, she's pretty nice."

AI Assistant

I calculated a gift amount for Sarah: 73.25 SEK. This is based on your 75 SEK budget for coworkers, with a positive bias since she's nice (nice score 7).

You

"Set up a 3000 SEK budget for January birthday gifts."

AI Assistant

✅ Created budget: 3000 SEK for Birthday gifts (January 1-31, 2025). I'll track your spending against this budget automatically.

You

"Kevin was really rude at the office party. Add him to the naughty list."

AI Assistant

😈 Kevin has been added to the naughty list. He'll automatically receive 0 (no gift) in future calculations, regardless of other parameters.

📖 Full MCP Documentation

🤝 Contributing

Help make gift-calc even better! We welcome contributions from everyone.

🐛

Report Issues

Found a bug? Have an idea? Create an issue on GitHub.

🔧

Submit Code

Fork the repo, make improvements, and submit a pull request.

⭐

Spread the Word

Star the repo and share gift-calc with your network!

Ready to get started?

Install gift-calc now and never guess gift amounts again!

📦 Install Now 📖 View on GitHub