Cronty MCP

A FastMCP server that enables AI agents to schedule notifications and reminders via Upstash QStash and NTFY.

Features

• Instant Push Notifications - Send immediate notifications with rich formatting, actions, and attachments
• One-off Scheduled Notifications - Schedule notifications for a specific future time using ISO 8601, date/time/timezone, or delay format
• Recurring Cron Notifications - Create persistent schedules using standard cron syntax

Available Tools

Tool	Description
health	Check server configuration and environment status
send_push_notification	Send an immediate push notification
schedule_notification	Schedule a one-off notification for a future time
schedule_cron_notification	Schedule recurring notifications using cron syntax
list_scheduled_notifications	List all recurring cron schedules (optionally filter by topic)
pause_schedule	Temporarily pause a cron schedule
resume_schedule	Resume a paused cron schedule
delete_schedule	Permanently delete a cron schedule

Prerequisites

• Python 3.13+
• uv package manager
• Docker Desktop 4.50+ (for Docker Sandboxes development)
• Upstash QStash account and token
• NTFY topic for receiving notifications (passed as notification_topic parameter to each tool)

Quickstart

1. Clone and Setup

git clone https://github.com/your-org/cronty-mcp.git
cd cronty-mcp
uv sync

2. Configure Environment

cp .env.example .env

Edit .env with your credentials:

QSTASH_TOKEN=your_qstash_token_here

# For local development without auth:
AUTH_DISABLED=true

# Or for production with auth:
# JWT_SECRET=your_secret_here  # Generate with: openssl rand -base64 48

Note: The NTFY topic is now specified per-request via the notification_topic parameter on each tool call, enabling multi-user and multi-tenant deployments.

3. Run the Server

uv run fastmcp run server.py

For development with the MCP Inspector:

uv run fastmcp dev server.py

Authentication

Cronty MCP supports bearer token authentication using JWT tokens signed with HS512.

Generating a JWT Secret

Generate a secure secret (minimum 64 characters):

# macOS/Linux
openssl rand -base64 48

# Or using Python
python -c "import secrets; print(secrets.token_urlsafe(48))"

Add the secret to your .env:

JWT_SECRET=your_generated_secret_here

Issuing Tokens

Issue tokens for users via CLI:

uv run python -m cronty token issue --email user@example.com

With custom expiration:

uv run python -m cronty token issue --email user@example.com --expires-in 30d

Supported duration formats: 30d, 12h, 1y, 365d

Disabling Authentication

For local development, disable auth by setting:

AUTH_DISABLED=true

Agent Configuration (Local Mode)

Configure your AI agent to connect to the local MCP server.

Note: These configurations run the server locally with AUTH_DISABLED=true for development.

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "cronty-mcp": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "server.py"]
    }
  }
}

Or use the CLI:

claude mcp add cronty-mcp -- uv run fastmcp run server.py

Claude Desktop

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "cronty-mcp": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "server.py"],
      "cwd": "/path/to/cronty-mcp"
    }
  }
}

Cursor

Add to your Cursor MCP configuration (.cursor/mcp.json in your project or global settings):

{
  "mcpServers": {
    "cronty-mcp": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "server.py"],
      "cwd": "/path/to/cronty-mcp"
    }
  }
}

VS Code

Add to your VS Code settings (.vscode/mcp.json or user settings):

{
  "mcpServers": {
    "cronty-mcp": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "server.py"],
      "cwd": "/path/to/cronty-mcp"
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration (~/.windsurf/mcp.json or project-level):

{
  "mcpServers": {
    "cronty-mcp": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "server.py"],
      "cwd": "/path/to/cronty-mcp"
    }
  }
}

Codex CLI

codex mcp add cronty-mcp -- uv run fastmcp run server.py

Gemini CLI

gemini mcp add cronty-mcp -- uv run fastmcp run server.py

FastMCP Cloud Deployment

When deployed to FastMCP Cloud, you can connect to your server using bearer token authentication.

Replace your-hostname with your actual FastMCP Cloud hostname (e.g., your-app-name.fastmcp.app).

Note: Bearer token authentication is a temporary solution for clients that don't yet support OAuth 2.0 Dynamic Client Registration (DCR). OAuth with DCR support via WorkOS/Authkit is planned as the preferred authentication method.

Environment Setup

Set your bearer token as an environment variable:

export CRONTY_TOKEN="your-token-here"

Issuing Tokens for Cloud Users

Before connecting, issue a token for each user:

uv run python -m cronty token issue --email user@example.com

Users will need this token to authenticate with the cloud-deployed server.

Obsidian

In the Obsidian MCP plugin settings, add a new server:

Field	Value
Server name	Cronty
Server URL	https://your-hostname.fastmcp.app/mcp
Authentication	Bearer Token
Token	(paste token from CLI)

Claude Code

Using CLI:

claude mcp add --transport http cronty-mcp https://your-hostname.fastmcp.app/mcp \
  --header "Authorization: Bearer ${CRONTY_TOKEN}"

Or add to .mcp.json:

{
  "mcpServers": {
    "cronty-mcp": {
      "type": "http",
      "url": "https://your-hostname.fastmcp.app/mcp",
      "headers": {
        "Authorization": "Bearer ${CRONTY_TOKEN}"
      }
    }
  }
}

Claude Desktop

Claude Desktop requires the mcp-remote wrapper to add custom headers. Add to claude_desktop_config.json:

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

{
  "mcpServers": {
    "cronty-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://your-hostname.fastmcp.app/mcp",
        "--header",
        "Authorization: Bearer YOUR_TOKEN"
      ]
    }
  }
}

Replace YOUR_TOKEN with your actual token from the CLI.

Codex CLI

Edit ~/.codex/config.toml:

[mcp_servers.cronty-mcp]
url = "https://your-hostname.fastmcp.app/mcp"
bearer_token_env_var = "CRONTY_TOKEN"

Then set the environment variable before running Codex.

Gemini CLI

Using CLI:

gemini mcp add cronty-mcp https://your-hostname.fastmcp.app/mcp \
  --transport http \
  --header "Authorization: Bearer ${CRONTY_TOKEN}"

Or edit settings.json:

{
  "mcpServers": {
    "cronty-mcp": {
      "httpUrl": "https://your-hostname.fastmcp.app/mcp",
      "headers": {
        "Authorization": "Bearer ${CRONTY_TOKEN}"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "cronty-mcp": {
      "url": "https://your-hostname.fastmcp.app/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CRONTY_TOKEN}"
      }
    }
  }
}

Note: Cursor uses ${env:VAR} syntax for environment variables.

VS Code

Add to .vscode/mcp.json:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "cronty-token",
      "description": "Cronty MCP Bearer Token",
      "password": true
    }
  ],
  "servers": {
    "cronty-mcp": {
      "type": "http",
      "url": "https://your-hostname.fastmcp.app/mcp",
      "headers": {
        "Authorization": "Bearer ${input:cronty-token}"
      }
    }
  }
}

VS Code will securely prompt for your token on first use.

FastMCP Python Client

import asyncio
from fastmcp import Client
from fastmcp.client.auth import BearerAuth

client = Client(
    "https://your-hostname.fastmcp.app/mcp",
    auth=BearerAuth("your-token-here")
)

async def main():
    async with client:
        await client.ping()

        tools = await client.list_tools()

        result = await client.call_tool(
            "send_push_notification",
            {"message": "Hello from Cronty!"}
        )
        print(result)

asyncio.run(main())

OpenAI SDK

import os
from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-4.1",
    tools=[
        {
            "type": "mcp",
            "server_label": "cronty-mcp",
            "server_url": "https://your-hostname.fastmcp.app/mcp",
            "headers": {
                "Authorization": f"Bearer {os.environ['CRONTY_TOKEN']}"
            },
            "require_approval": "never",
        },
    ],
    input="Send me a test notification",
)

OAuth Authentication (Coming Soon)

OAuth 2.0 with Dynamic Client Registration (DCR) support via WorkOS/Authkit is planned. This will enable:

• Automatic token refresh
• Secure authorization flows
• No manual token management

Clients with native OAuth DCR support (Claude Code, VS Code, Cursor) will be able to authenticate without bearer tokens once implemented.

Evaluations

Run evaluations against your MCP server using Claude to verify tool effectiveness.

Setup

Add your Anthropic API key to .env:

# In .env
ANTHROPIC_API_KEY=your_api_key_here

Note: Requires an Anthropic API key from console.anthropic.com. Claude Max subscription does not include API access.

Create an Evaluation File

Create an XML file with question-answer pairs (see evaluation.xml for examples):

<evaluation>
   <qa_pair>
      <question>Use the health tool. Is the server healthy? Answer: Yes or No.</question>
      <answer>Yes</answer>
   </qa_pair>
</evaluation>

Run Evaluations

From Project Root

uv run python .claude/skills/fastmcp-builder/scripts/evaluation.py \
    -c "uv run fastmcp run server.py" \
    evaluation.xml

Against HTTP server:

uv run python .claude/skills/fastmcp-builder/scripts/evaluation.py \
    -t http \
    -u https://your-hostname.fastmcp.app/mcp \
    evaluation.xml

With custom model and output:

uv run python .claude/skills/fastmcp-builder/scripts/evaluation.py \
    -c "uv run fastmcp run server.py" \
    -m claude-sonnet-4-20250514 \
    -o report.md \
    evaluation.xml

From Scripts Directory (Alternative)

If you don't want evaluation dependencies in your project:

cd .claude/skills/fastmcp-builder/scripts
uv sync
uv run python evaluation.py \
    -c "uv run fastmcp run server.py" \
    --cwd ../../../.. \
    ../../../../evaluation.xml

Evaluation Guidelines

• Questions must be READ-ONLY, INDEPENDENT, NON-DESTRUCTIVE, IDEMPOTENT
• Answers must be single, verifiable values (not lists or objects)
• Answers must be STABLE (won't change over time)
• Create challenging questions that require multiple tool calls

See .claude/skills/fastmcp-builder/reference/evaluation.md for the complete guide.

Development

Install Dependencies

uv sync

Run Tests

uv run pytest

Linting

uv run ruff check .
uv run ruff check . --fix
uv run ruff format .

Testing with Claude Code

Local Mode (stdio)

For local development, use stdio transport with auth disabled. Set in .env:

AUTH_DISABLED=true

The repo includes .mcp.json for local testing:

{
  "mcpServers": {
    "cronty-mcp": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "server.py"]
    }
  }
}

Then run Claude Code from this directory - it will automatically detect the MCP server.

Cloud Mode (HTTP with bearer token)

To test against FastMCP Cloud deployment:

1. Set your token:

   export CRONTY_TOKEN="your-token-here"

2. Update .mcp.json to use HTTP transport:

   {
     "mcpServers": {
       "cronty-mcp": {
         "type": "http",
         "url": "https://your-hostname.fastmcp.app/mcp",
         "headers": {
           "Authorization": "Bearer ${CRONTY_TOKEN}"
         }
       }
     }
   }

3. Run Claude Code with the env var set.

Claude Code with Docker Sandboxes

Run Claude Code in an isolated Docker container with all dependencies pre-installed.

Build the Custom Template

docker build -t cronty-dev .

Set Environment Variables

The .env file is not mounted in the container for security. Set variables in your shell:

# Option 1: Source from .env file
set -a; source .env; set +a

# Option 2: Add to ~/.zshrc or ~/.bashrc for persistence
export QSTASH_TOKEN=your_qstash_token_here
export ANTHROPIC_API_KEY=your_api_key_here  # Required for running evaluations
export JWT_SECRET=your_jwt_secret_here      # Required if AUTH_DISABLED is not set

Run Claude Code in Sandbox

# Development mode (auth disabled)
docker sandbox run \
  -e QSTASH_TOKEN=$QSTASH_TOKEN \
  -e AUTH_DISABLED=true \
  --template cronty-dev claude

# Continue a previous conversation
docker sandbox run \
  -e QSTASH_TOKEN=$QSTASH_TOKEN \
  -e AUTH_DISABLED=true \
  --template cronty-dev claude -c

# With a direct prompt
docker sandbox run \
  -e QSTASH_TOKEN=$QSTASH_TOKEN \
  -e AUTH_DISABLED=true \
  --template cronty-dev claude "Run the tests"

# With auth enabled and evaluation support
docker sandbox run \
  -e QSTASH_TOKEN=$QSTASH_TOKEN \
  -e JWT_SECRET=$JWT_SECRET \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  --template cronty-dev claude

Claude Settings in Sandbox

Global Claude settings (~/.claude/settings.json) are not available inside the sandbox due to security restrictions. To use custom settings (hooks, permissions, preferences), create a local settings file in the project:

# Create local settings file
cp ~/.claude/settings.json .claude/settings.local.json

The .claude/settings.local.json file is mounted with the project and will be used by Claude Code inside the sandbox.

Available Commands Inside Sandbox

All uv commands work inside the sandbox:

uv run pytest                    # Run tests
uv run fastmcp dev server.py     # Start dev server with MCP Inspector
uv run ruff check .              # Lint code
uv add some-package              # Add dependencies

What's Included

The Docker Sandbox template includes:

• Claude Code with automatic credential handling
• Python 3.13 with uv package manager
• All project dependencies pre-installed
• Docker CLI, GitHub CLI, Git, Node.js, Go
• Non-root agent user with sudo privileges

License

MIT