Content
# @timergy/mcp
[](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
