# @timergy/mcp

[![Smithery](https://smithery.ai/badge/timergy/timergy)](https://smithery.ai/server/timergy/timergy)

MCP server for [Timergy](https://timergy.com) - the scheduling poll app. Create polls, vote on time slots, and finalize meetings directly from AI agents like Claude, ChatGPT, and Gemini.

**No authentication required.** Works out of the box.

## What is Timergy?

Timergy is a scheduling poll service (like Doodle or When2Meet). You create a poll with time slot options, share it with participants, everyone votes on their availability, and you pick the best time.

## Quick Start

### Claude Desktop / Claude Code

Add to your MCP config (`~/.claude/claude_desktop_config.json` or project `.mcp.json`):

```json
{
  "mcpServers": {
    "timergy": {
      "command": "npx",
      "args": ["@timergy/mcp"]
    }
  }
}
```

Then just ask:

> "Create a poll for dinner next Friday or Saturday evening"

### Smithery (Remote, no install)

```
smithery mcp add timergy/timergy
```

Or connect directly via `https://timergy--timergy.run.tools`

### Other MCP Clients

Any MCP-compatible client can use this server. Supports stdio (local) and Streamable HTTP (remote at `https://api.timergy.com/mcp`).

## Tools

### `create_poll`

Create a scheduling poll with time slot options.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | yes | Poll title |
| `options` | array | yes | Time slots (`{start, end}` in ISO 8601 with timezone) |
| `description` | string | no | Poll description |
| `deadline` | string | no | Voting deadline (ISO 8601) |
| `location` | string | no | Event location |
| `creatorName` | string | no | Name shown as poll creator |

```
"Create a poll called 'Team Lunch' with slots on Monday 12-13 and Tuesday 12-13"
```

Returns: poll URL (to share), passphrase (for admin access), option IDs.

### `get_poll`

Get poll details and time slot options (no votes). Use this to retrieve option IDs before voting or finalizing.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pollId` | string | yes | Poll UUID |

```
"Show me the details of poll abc-123"
```

### `vote_on_poll`

Submit votes on a poll. Each vote maps a time slot to yes/maybe/no.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pollId` | string | yes | Poll UUID |
| `voterName` | string | yes | Name of the voter |
| `voterEmail` | string | no | Voter email (for notifications) |
| `votes` | array | yes | `{optionId, availability}` where availability is `yes`/`maybe`/`no` |

```
"Vote 'yes' for Monday and 'no' for Tuesday on poll abc-123 as Max"
```

### `get_results`

See who voted and which time slots are most popular.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pollId` | string | yes | Poll UUID |

```
"Show me the results for poll abc-123"
```

### `finalize_poll`

Lock in the winning time slot. Notifies participants who provided an email.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pollId` | string | yes | Poll UUID |
| `optionId` | string | yes | Winning time slot UUID |
| `passphrase` | string | no | Admin passphrase (auto-remembered from create_poll) |

```
"Finalize poll abc-123 with the Monday slot"
```

## Workflow

```
1. create_poll  ->  Get poll URL + passphrase
2. Share URL    ->  Send to participants
3. get_results  ->  See who voted yes/maybe/no
4. finalize_poll -> Pick the best time, lock it in
```

The passphrase from step 1 is automatically remembered for step 4 within the same session.

## REST API

The MCP server calls the Timergy Open API under the hood. You can also use the API directly:

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/open/polls` | Create a poll |
| `GET` | `/api/open/polls/:id` | Get poll details |
| `GET` | `/api/open/polls/:id/options` | Get time slots |
| `GET` | `/api/open/polls/:id/results` | Get vote results |
| `POST` | `/api/open/polls/:id/vote` | Submit votes |
| `POST` | `/api/open/polls/:id/admin-token` | Get admin token |
| `POST` | `/api/open/polls/:id/finalize` | Finalize poll |

Base URL: `https://api.timergy.com`

OpenAPI spec: `https://api.timergy.com/api/open/openapi.json`

## Configuration

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `TIMERGY_API_URL` | `https://api.timergy.com` | API base URL |

For local development:

```json
{
  "mcpServers": {
    "timergy": {
      "command": "npx",
      "args": ["@timergy/mcp"],
      "env": { "TIMERGY_API_URL": "http://localhost:4000" }
    }
  }
}
```

## Rate Limits

| Action | Limit |
|--------|-------|
| Create poll | 5 per hour |
| Vote | 20 per minute |
| Get poll/results | 60 per minute |
| Admin token | 5 per 10 minutes |
| Finalize | 3 per hour |

## License

MIT