@timergy/mcp

MCP server for Timergy - 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):

{
  "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 | | autoFinalize | boolean | no | Auto-finalize when deadline passes (requires deadline) | | timezone | string | no | IANA timezone for display (e.g. Europe/Berlin) | | invitees | array | no | People to invite: {email, name?} (max 10 unauthenticated; max 50 with API key/OAuth) |

"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.

When an API key or OAuth token is configured, the poll is created on the user's account instead: no passphrase is returned, and update_poll, invite_to_poll, list_my_polls, and finalization work via the same auth.

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"

suggest_best_option

Analyze votes and rank all time slots by popularity. Scoring: yes = 1, maybe = 0.5. Tiebreak: fewest no-votes, then earliest start.

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

"Which time works best for poll abc-123?"

Returns: all options ranked with scores, vote counts, and the recommended best option.

send_reminder

Email participants who haven't voted yet. Only works for polls with email invitations.

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

"Send a reminder for poll abc-123"

auto_finalize

Automatically pick the best-voted option and finalize the poll. Combines suggest + finalize in one step.

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

"Auto-finalize poll abc-123 with the most popular time"

create_survey

Create a choice-based poll where participants vote on text options instead of time slots. Use for decisions like "Where should we eat?", "Which logo?", or "What activity?".

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | title | string | yes | Survey title | | options | array | yes | Text options to vote on (at least 2 strings) | | description | string | no | Survey description | | creatorName | string | no | Name shown as poll creator | | invitees | array | no | People to invite: {email, name?} |

"Create a survey called 'Team Dinner' with options 'Italian', 'Japanese', 'Mexican'"

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

ignore_event

Ignore a calendar event so it won't show as a conflict when checking poll time slots. Get the eventId, connectionId, and provider from the conflictEventDetails field in check_conflicts results. Requires API key authentication.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | eventId | string | yes | Calendar event ID (from check_conflicts) | | title | string | yes | Event title | | connectionId | string | yes | Calendar connection ID (from check_conflicts) | | provider | string | yes | Calendar provider (e.g. google, microsoft, caldav) | | seriesId | string | no | Recurring event series ID | | seriesWide | boolean | no | Ignore all instances of a recurring event (default: true) | | apiKey | string | yes | Timergy API key (X-API-Key) |

"Ignore my daily standup when checking conflicts for poll abc-123"

list_ignored_events

List all calendar events the user has chosen to ignore from conflict detection. Requires API key authentication.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | apiKey | string | yes | Timergy API key (X-API-Key) |

"Show me which calendar events I'm ignoring"

Returns: list of ignored events with IDs, titles, and connection IDs.

unignore_event

Stop ignoring a previously ignored calendar event, so it will appear as a conflict again. Pass the ignore rule ID (from list_ignored_events), not the calendar event ID. Requires API key authentication.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | yes | Ignore rule ID (from list_ignored_events) | | apiKey | string | yes | Timergy API key (X-API-Key) |

"Stop ignoring my daily standup in conflict checks"

check_conflicts

Check which poll time slots conflict with the creator's connected calendars (Google, Outlook, iCloud, CalDAV). Requires API key authentication.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | pollId | string | yes | Poll UUID | | apiKey | string | yes | Timergy API key (X-API-Key) |

"Check my calendar conflicts for poll abc-123"

Returns: each option with a conflict flag, conflicting event titles (conflictEvents), and conflictEventDetails (eventId, connectionId, provider) for use with ignore_event.

list_contacts

Search the user's Timergy address book by name or email. Contacts are auto-captured from invitations, votes, bookings, and Meeting Autopilot groups. Requires API key authentication.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | apiKey | string | yes | Timergy API key (X-API-Key) | | query | string | no | Search query to filter by name or email |

"Find Sarah's email in my contacts"

invite_to_poll

Invite people to an existing poll by email. Invitees receive an email with a direct voting link. Requires API key authentication.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | pollId | string | yes | Poll UUID | | apiKey | string | yes | Timergy API key (X-API-Key) | | invitees | array | yes | People to invite: {email, name?} (max 50) |

"Invite [email protected] to poll abc-123"

Poll Management (authenticated)

list_my_polls

List all polls created by the authenticated user. Requires auth (oauthToken or apiKey).

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | oauthToken | string | no | OAuth access token (from Timergy OAuth flow) | | apiKey | string | no | Timergy API key (X-API-Key) |

"Show me all my polls"

Returns: array of polls with title, status, participantCount, optionCount, createdAt.

update_poll

Update an existing poll's title, description, deadline, or location. Requires auth. Pass pollId and only the fields you want to change.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | pollId | string | yes | Poll UUID | | title | string | no | New poll title | | description | string | no | New description | | deadline | string | no | New voting deadline (ISO 8601) | | location | string | no | New event location | | oauthToken | string | no | OAuth access token | | apiKey | string | no | Timergy API key (X-API-Key) |

"Change the title of poll abc-123 to 'Team Offsite Planning'"

delete_poll

Archive a poll so it disappears from your active list. Requires auth. Other participants are unaffected; polls are globally removed only by the automatic cleanup after the retention window (10 days past the event date).

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | pollId | string | yes | Poll UUID | | oauthToken | string | no | OAuth access token | | apiKey | string | no | Timergy API key (X-API-Key) |

"Delete poll abc-123"

reopen_poll

Reopen a finalized poll so participants can vote again. Requires auth. Clears the finalized option and any calendar events created during finalization.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | pollId | string | yes | Poll UUID | | oauthToken | string | no | OAuth access token | | apiKey | string | no | Timergy API key (X-API-Key) |

"Reopen poll abc-123 for more votes"

Webhooks (authenticated)

create_webhook

Subscribe to poll events via HTTPS webhook. Requires auth. Your endpoint will receive POST requests when events occur.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | url | string | yes | HTTPS webhook endpoint URL | | events | array | yes | Events to subscribe to: vote.received, poll.finalized, poll.reminder_sent, poll.deadline_approaching | | oauthToken | string | no | OAuth access token | | apiKey | string | no | Timergy API key (X-API-Key) |

"Create a webhook at https://example.com/hook for vote.received and poll.finalized events"

list_webhooks

List all active webhook subscriptions. Requires auth.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | oauthToken | string | no | OAuth access token | | apiKey | string | no | Timergy API key (X-API-Key) |

"Show me my webhook subscriptions"

Returns: array of webhooks with id, url, events, createdAt.

delete_webhook

Delete a webhook subscription by ID. Requires auth.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | webhookId | string | yes | Webhook subscription ID (from list_webhooks) | | oauthToken | string | no | OAuth access token | | apiKey | string | no | Timergy API key (X-API-Key) |

"Delete webhook subscription xyz-456"

Workflow

1. create_poll         ->  Get poll URL + passphrase
2. Share URL           ->  Send to participants
3. send_reminder       ->  Nudge non-voters (optional)
4. suggest_best_option ->  See ranked results with scores
5. finalize_poll       ->  Pick the best time, lock it in
   (or auto_finalize   ->  Let Timergy pick automatically)

The passphrase from step 1 is automatically remembered for steps 3-5 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 | | GET | /api/open/polls/:id/suggest | Suggest best option | | POST | /api/open/polls/:id/send-reminder | Send reminder to non-voters | | POST | /api/open/polls/:id/auto-finalize | Auto-finalize with best option | | GET | /api/v1/contacts | Search contacts (auth required) | | POST | /api/v1/polls/:id/invite | Invite people to poll (auth required) | | GET | /api/v1/polls | List user's polls (auth required) | | PATCH | /api/v1/polls/:id | Update poll (auth required) | | DELETE | /api/v1/polls/:id | Archive poll for the user (auth required) | | POST | /api/v1/polls/:id/reopen | Reopen finalized poll (auth required) | | POST | /api/v1/webhooks | Create webhook subscription (auth required) | | GET | /api/v1/webhooks | List webhook subscriptions (auth required) | | DELETE | /api/v1/webhooks/:id | Delete webhook subscription (auth required) |

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:

{
  "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 | | Suggest | 30 per minute | | Send reminder | 3 per hour (per poll) | | Auto-finalize | 2 per hour (per poll) |

License

MIT