<p align="center">
  <img src="https://raw.githubusercontent.com/Jacob-Stokes/jhabit/main/frontend/public/logo.svg" alt="jhabit" width="96" />
</p>

<h1 align="center">jhabit-mcp</h1>

Standalone MCP server for [jhabit](https://github.com/Jacob-Stokes/jhabit) — a habit and quit tracker. Connects to your jhabit instance via API key and exposes tracking tools to MCP clients like Claude Desktop and Claude Code.

> **Note:** jhabit also has a [built-in remote MCP server](https://github.com/Jacob-Stokes/jhabit) using OAuth 2.1 + Streamable HTTP, for cloud-based MCP clients. This standalone server is for local stdio-based clients.

## Setup

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "jhabit": {
      "command": "npx",
      "args": ["-y", "jhabit-mcp"],
      "env": {
        "JHABIT_URL": "https://your-jhabit-instance.com",
        "JHABIT_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Claude Code

```json
{
  "mcpServers": {
    "jhabit": {
      "command": "npx",
      "args": ["-y", "jhabit-mcp"],
      "env": {
        "JHABIT_URL": "https://your-jhabit-instance.com",
        "JHABIT_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### From source

```bash
git clone https://github.com/Jacob-Stokes/jhabit-mcp.git
cd jhabit-mcp
npm install && npm run build
JHABIT_URL=https://your-instance.com JHABIT_API_KEY=your-key node dist/index.js
```

## Getting an API Key

1. Log into your jhabit instance
2. Go to Settings > API Keys
3. Create a new key and copy it

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `JHABIT_URL` | Yes | Base URL of your jhabit instance |
| `JHABIT_API_KEY` | Yes | API key for authentication |

## Available Tools

### `list_trackers`
List all habits and/or quits.
- `type` (optional): Filter by `"habit"` or `"quit"`

### `create_tracker`
Create a new habit or quit tracker.
- `name` (required): Tracker name, e.g. "Meditate" or "Smoking"
- `type` (required): `"habit"` or `"quit"`
- `emoji` (optional): Emoji icon

### `log_entry`
Log an entry. For habits = "I did it". For quits = "I slipped up".
- `tracker_id` (required): Tracker ID
- `timestamp` (optional): ISO timestamp, defaults to now
- `note` (optional): Note

### `delete_entry`
Delete an entry by ID.
- `entry_id` (required): Entry ID

### `get_tracker_stats`
Get stats for a tracker.
- `tracker_id` (required): Tracker ID

Returns streaks (current/best) for habits, or abstinence time and slip count for quits.