@timergy/mcp

@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)

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

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"

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"

list_contacts

Search the user's Timergy address book by name or email. Contacts are auto-captured from invitations, votes, bookings, and buddy 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 [e-mail] to poll abc-123"

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)

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