Cronty

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
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.58+ (for Docker Sandboxes with microVM isolation)
• 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 [email protected]

With custom expiration:

uv run python -m cronty token issue --email [email protected] --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 [email protected]

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_EVAL_API_KEY=your_api_key_here

Note: Requires an Anthropic API key from console.anthropic.com. Claude Max subscription does not include API access. The evaluation harness uses ANTHROPIC_EVAL_API_KEY (not ANTHROPIC_API_KEY) to avoid accidental charges when using Claude Code with a different billing setup.

Create an Evaluation File

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

<evaluation>
   <qa_pair>
      <question>Use the send_push_notification tool with message "test" and notification_topic "demo". Did it succeed? Answer: Yes or No.</question>
      <answer>Yes</answer>
   </qa_pair>
</evaluation>

Run Evaluations

From Project Root

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

Against HTTP server:

uv run python plugins/fastmcp-builder/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 plugins/fastmcp-builder/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 plugins/fastmcp-builder/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 plugins/fastmcp-builder/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.

Requires Docker Desktop 4.58+ with microVM-based sandboxes.

Migrating from Docker Desktop < 4.58

If upgrading from an older Docker Desktop version, remove old container-based sandboxes first:

# Remove old sandbox containers
docker rm -f $(docker ps -q -a --filter="label=docker/sandbox=true")

# Remove credential volume
docker volume rm docker-claude-sandbox-data

Build the Custom Template

docker build -t cronty-dev .

Set Environment Variables

Docker Sandboxes run via a daemon that reads environment variables from your shell config files. Add these to ~/.zshrc or ~/.bashrc:

# Required
export QSTASH_TOKEN=your_qstash_token_here
export AUTH_DISABLED=true  # For development mode

# Optional (for production/evaluations)
export JWT_SECRET=your_jwt_secret_here           # Required if AUTH_DISABLED is not set
export ANTHROPIC_EVAL_API_KEY=your_api_key_here  # Required for running evaluations

After adding, apply changes and restart Docker Desktop:

source ~/.zshrc  # or ~/.bashrc
# Then restart Docker Desktop for the daemon to pick up new variables

Run Claude Code in Sandbox

# Run with custom template
docker sandbox run --template cronty-dev --load-local-template claude .

# Continue a previous conversation
docker sandbox run --template cronty-dev --load-local-template claude . -- -c

# With a direct prompt
docker sandbox run --template cronty-dev --load-local-template claude . -- -p "Run the tests"

# Run with a named sandbox (for persistence)
docker sandbox run --name cronty --template cronty-dev --load-local-template 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

Plugin Marketplace

This repository includes the fastmcp-builder skill as a Claude Code plugin, providing comprehensive guidance for building production-quality MCP servers with FastMCP.

Installation

1. Add the marketplace:

   /plugin marketplace add cronty-com/cronty-mcp
   

2. Install the plugin:

   /plugin install fastmcp-builder@cronty-plugins
   

Usage

Invoke the skill to get guidance on building FastMCP servers:

/fastmcp-builder

The plugin includes:

• SKILL.md - Comprehensive 4-phase guide for building MCP servers (research, implementation, review, evaluation)
• reference/best-practices.md - Naming conventions, response formats, security patterns
• reference/python-guide.md - Pydantic v2 patterns, async operations, pagination
• reference/evaluation.md - Guide for creating evaluation test suites
• scripts/evaluation.py - Evaluation harness for testing MCP servers with Claude

For running evaluations, see the Evaluations section above.

License

MIT