# Timers Studio — MCP Server

[![smithery badge](https://smithery.ai/badge/contact-ymj4/timers-studio)](https://smithery.ai/servers/contact-ymj4/timers-studio)

Public Model Context Protocol server for [Timers Studio](https://timers.studio), the professional broadcast timer platform. Hosted at `https://mcp.timers.studio/mcp`. Lets Claude Desktop, ChatGPT, Gemini, Perplexity, and any MCP-aware client answer prospect questions about Timers Studio with first-party data: competitive positioning, use cases, personas, and recommended plans.

## Scope

**Read-only marketing surface.** The server exists to help convert prospects researching Timers Studio in an LLM client. It returns positioning, competitor comparisons, use cases, and personas.

**It does not control studios.** Studio operations (start, pause, reset, agenda transport, message broadcast) live exclusively in the authenticated REST API on `api.timers.studio` and require a user account. That surface is intentionally not exposed via MCP.

## Tools

All four tools are read-only and require no authentication.

| Tool | Description |
| --- | --- |
| `get_competitive_arsenal` | Full machine-readable arsenal: 7 competitors, 4 use cases, 5 personas. |
| `find_competitor` | Positioning vs one competitor (slug or name). Slugs: `stagetimer`, `shoflo`, `propresenter`, `cuez`, `planning-center-timer`, `dsan`, `cuetimer`. |
| `find_use_case` | Fit + workflow for one use case. Slugs: `broadcast-tv`, `live-event`, `conference`, `church`. |
| `find_persona` | JTBD + recommended plan for one role. Slugs: `show-caller`, `broadcast-engineer`, `event-producer`, `av-integrator`, `developer`. |

All tools fetch `https://timers.studio/api/ai/context` (cached 5 min in-memory).

## Wire protocol

JSON-RPC 2.0 over HTTP, Streamable HTTP transport, stateless mode. Endpoint: `https://mcp.timers.studio/mcp`. Protocol version: `2025-03-26`.

Supported methods: `initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/templates/list`, `prompts/list`, `ping`, `notifications/*`.

## Connecting from a client

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "timers-studio": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.timers.studio/mcp"]
    }
  }
}
```

Restart Claude Desktop. Ask: "Compare Timers Studio with Stagetimer."

### Smithery

[![smithery badge](https://smithery.ai/badge/contact-ymj4/timers-studio)](https://smithery.ai/servers/contact-ymj4/timers-studio)

Already published. Install with one click from the Smithery marketplace.

### Generic HTTP MCP client

Point at `https://mcp.timers.studio/mcp` with `Content-Type: application/json` and JSON-RPC 2.0 payloads.

```bash
curl -X POST https://mcp.timers.studio/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Local development

```bash
npm install
npm run dev      # wrangler dev on http://localhost:8787
```

Smoke tests:

```bash
# tools/list
curl -X POST http://localhost:8787/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq

# call a read tool
curl -X POST http://localhost:8787/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"find_competitor","arguments":{"slug":"stagetimer"}}}' | jq
```

## Deployment

Hosted on Cloudflare Workers. To deploy your own fork:

```bash
npx wrangler login
npm run deploy
```

Then configure your Cloudflare zone:
1. Add a DNS CNAME record (e.g. `mcp` → 100% proxy).
2. Workers Routes → bind `mcp.<your-domain>/*` to the worker.

## Security model

- Read-only surface. Same data as `https://timers.studio/api/ai/context`, served via JSON-RPC instead of REST.
- No Bearer token, no auth, no forwarding to upstream APIs. The Worker has no credentials, no secrets, no path to the Timers Studio backend.
- Stateless. Nothing is cached per-user.
- CORS allows any origin on `/mcp` (MCP clients have no consistent Origin), appropriate for a public read endpoint.

## Architecture

```
LLM client (Claude / ChatGPT / Gemini / Perplexity / IDE)
      │
      │  JSON-RPC 2.0 over HTTPS
      ▼
mcp.timers.studio/mcp  (Cloudflare Worker, stateless)
      │
      │  GET (cached 5 min)
      ▼
timers.studio/api/ai/context  (read-only marketing JSON)
```

The Worker is a thin JSON-RPC adapter on top of the public `/api/ai/context` endpoint. The competitive arsenal lives at `timers.studio` and is the single source of truth.

## Related projects

- Timers Studio platform: [timers.studio](https://timers.studio)
- Documentation: [docs.timers.studio](https://docs.timers.studio)
- AI manifest: [timers.studio/api/ai/manifest](https://timers.studio/api/ai/manifest)
- Companion module: [github.com/bitfocus/companion-module-timers-studio](https://github.com/bitfocus/companion-module-timers-studio)

## License

MIT. See [LICENSE](LICENSE).