# tickstem/mcp

[![Glama](https://glama.ai/mcp/servers/tickstem/mcp/badge)](https://glama.ai/mcp/servers/tickstem/mcp)
[![smithery badge](https://smithery.ai/badge/tickstem-mcp--tickstem-info)](https://smithery.ai/servers/tickstem-info/tickstem-mcp)

MCP server for [Tickstem](https://tickstem.dev) — exposes cron job scheduling, uptime monitoring, heartbeat monitoring, and email verification as native tools for AI coding assistants (Claude, Cursor, Copilot, and any MCP-compatible agent).

Let your AI assistant register cron jobs, create uptime monitors with response assertions, manage heartbeat monitors, verify email addresses, and query results — while you write the app code.

## Install

**Download a pre-built binary** (no Go required):

| Platform | Binary |
|----------|--------|
| macOS (Apple Silicon) | `tsk-mcp-darwin-arm64` |
| macOS (Intel) | `tsk-mcp-darwin-amd64` |
| Linux (x86-64) | `tsk-mcp-linux-amd64` |
| Linux (ARM64) | `tsk-mcp-linux-arm64` |
| Windows (x86-64) | `tsk-mcp-windows-amd64.exe` |

Download from [Releases](https://github.com/tickstem/mcp/releases), make executable, and place on your `PATH`:

```bash
# macOS / Linux example
chmod +x tsk-mcp-darwin-arm64
mv tsk-mcp-darwin-arm64 /usr/local/bin/tsk-mcp
```

**Or install with Go:**

```bash
go install github.com/tickstem/mcp/cmd/tsk-mcp@latest
```

## Quick start

```bash
export TICKSTEM_API_KEY=tsk_your_key_here
tsk-mcp
```

The server speaks the [Model Context Protocol](https://modelcontextprotocol.io) over stdio — connect it to any MCP-compatible client.

## Claude Code

Add to your `~/.claude/claude_desktop_config.json` (or equivalent):

```json
{
  "mcpServers": {
    "tickstem": {
      "command": "tsk-mcp",
      "env": {
        "TICKSTEM_API_KEY": "tsk_your_key_here"
      }
    }
  }
}
```

## Available tools

### Cron jobs

| Tool | Description |
|------|-------------|
| `list_jobs` | List all cron jobs in the account |
| `get_job` | Get a cron job by ID |
| `register_job` | Register a new cron job (name, schedule, endpoint) |
| `update_job` | Update an existing job — only provided fields change |
| `pause_job` | Pause a job so it no longer fires |
| `resume_job` | Resume a paused or failing job |
| `delete_job` | Permanently delete a job and its execution history |
| `list_executions` | List execution history for a job, most recent first |

### Uptime monitoring

| Tool | Description |
|------|-------------|
| `list_monitors` | List all monitors — status, URL, interval, SSL expiry, assertions |
| `create_monitor` | Create a monitor with optional response assertions (status code, response time, body) |
| `get_monitor` | Get a monitor by ID |
| `pause_monitor` | Pause a monitor so it stops polling |
| `resume_monitor` | Resume a paused monitor |
| `delete_monitor` | Permanently delete a monitor and its check history |
| `list_monitor_checks` | List recent checks — status, HTTP code, duration, error, SSL expiry |

#### Response assertions

`create_monitor` accepts an `assertions` parameter — a JSON array of conditions that must all pass for a check to be considered up. When assertions are set they replace the default 2xx/3xx logic.

```json
[
  { "source": "status_code",   "comparison": "eq",       "target": "200"              },
  { "source": "response_time", "comparison": "lt",       "target": "2000"             },
  { "source": "body",          "comparison": "contains", "target": "\"status\":\"ok\"" }
]
```

| Source | Valid comparisons | Target |
|--------|------------------|--------|
| `status_code` | `eq` `ne` `lt` `lte` `gt` `gte` | integer string |
| `response_time` | `eq` `ne` `lt` `lte` `gt` `gte` | integer string (ms) |
| `body` | `eq` `ne` `contains` `not_contains` | plain string |

### Heartbeat monitoring

| Tool | Description |
|------|-------------|
| `list_heartbeats` | List all heartbeats — status, token, interval, grace window, last ping time |
| `create_heartbeat` | Create a heartbeat monitor (dead-man's switch) |
| `get_heartbeat` | Get a heartbeat by ID |
| `update_heartbeat` | Update name, interval, or grace window |
| `pause_heartbeat` | Suppress alerts during planned downtime |
| `resume_heartbeat` | Resume alerting after a pause |
| `delete_heartbeat` | Permanently delete a heartbeat and its ping history |
| `ping_heartbeat` | Record a successful job run — no API key needed, token is the credential |
| `list_heartbeat_pings` | List recent pings for a heartbeat, most recent first |

### Email verification

| Tool | Description |
|------|-------------|
| `verify_email` | Check syntax, MX records, disposable domain, and role-based prefix |
| `list_verify_history` | List past verification results for the account |

## Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `TICKSTEM_API_KEY` | Yes | API key from [app.tickstem.dev](https://app.tickstem.dev) |
| `TICKSTEM_BASE_URL` | No | Override API base URL (e.g. `http://localhost:8080/v1` for local dev) |

## Local development

```bash
export TICKSTEM_API_KEY=tsk_your_key_here
export TICKSTEM_BASE_URL=http://localhost:8080/v1
go run ./cmd/tsk-mcp
```

## SDKs

The MCP server handles infrastructure management from your AI assistant. For application code, use the SDK that matches your language:

| Language | Install | Docs |
|----------|---------|------|
| Python | `pip install tickstem` | [github.com/tickstem/python](https://github.com/tickstem/python) |
| Go (cron) | `go get github.com/tickstem/cron` | [pkg.go.dev](https://pkg.go.dev/github.com/tickstem/cron) |
| Go (uptime) | `go get github.com/tickstem/uptime` | [pkg.go.dev](https://pkg.go.dev/github.com/tickstem/uptime) |
| Go (heartbeat) | `go get github.com/tickstem/heartbeat` | [pkg.go.dev](https://pkg.go.dev/github.com/tickstem/heartbeat) |
| Go (verify) | `go get github.com/tickstem/verify` | [pkg.go.dev](https://pkg.go.dev/github.com/tickstem/verify) |
| Node.js | `npm install @tickstem/cron` | [github.com/tickstem/node](https://github.com/tickstem/node) |

All SDKs use the same API key.

## Get an API key

[app.tickstem.dev](https://app.tickstem.dev) — free tier includes 1,000 cron executions, 5 uptime monitors, 5 heartbeat monitors, and 500 email verifications per month.

## License

MIT