Skip to main content
Glama
README.md
# otipi-mcp

MCP server for [Otipi](https://otipi.co.il), an SMS, email and OTP API for Israel. It lets AI agents (Claude Code, Cursor, Claude Desktop, VS Code) send and verify one-time codes in test mode, check delivery, and generate ready-to-paste integration code for Next.js, Supabase and Express.

Zero runtime dependencies. Plain Node.js (>= 18), stdio transport.


## Remote server, nothing to install

The same tools run at **https://otipi.co.il/mcp** (Streamable HTTP).

- **Claude.ai, ChatGPT** and other apps with connectors: add a custom connector with that address. You sign in to Otipi and allow it (OAuth); the app gets a test key of its own that you can revoke in the dashboard.
- **Claude Code**: `claude mcp add --transport http otipi https://otipi.co.il/mcp --header "Authorization: Bearer sk_test_..."`
- **Cursor** (`.cursor/mcp.json`): `{ "mcpServers": { "otipi": { "url": "https://otipi.co.il/mcp", "headers": { "Authorization": "Bearer sk_test_..." } } } }`
- **VS Code**: `{ "name": "otipi", "type": "http", "url": "https://otipi.co.il/mcp", "headers": { "Authorization": "Bearer sk_test_..." } }`

A free test key comes in one click after sign-up at https://otipi.co.il/signup. This npm package is the local alternative for clients that only run stdio servers.

## Get a key

Sign up at https://otipi.co.il/signup to get a free test key (`sk_test_...`). Live keys (`sk_live_...`) send real messages and need a subscription.

The key is read only from the `OTIPI_KEY` environment variable (`OTIPI_API_KEY` is accepted as a fallback). `OTIPI_BASE_URL` is optional and defaults to `https://otipi.co.il`.

## Install

### Claude Code

```
claude mcp add otipi --env OTIPI_KEY=sk_test_... -- npx -y otipi-mcp
```

### Cursor

`.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "otipi": {
      "command": "npx",
      "args": ["-y", "otipi-mcp"],
      "env": { "OTIPI_KEY": "sk_test_..." }
    }
  }
}
```

### Claude Desktop

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "otipi": {
      "command": "npx",
      "args": ["-y", "otipi-mcp"],
      "env": { "OTIPI_KEY": "sk_test_..." }
    }
  }
}
```

### VS Code

`.vscode/mcp.json`:

```json
{
  "servers": {
    "otipi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "otipi-mcp"],
      "env": { "OTIPI_KEY": "sk_test_..." }
    }
  }
}
```

On Windows, if `npx` is not found by your client, use `"command": "cmd", "args": ["/c", "npx", "-y", "otipi-mcp"]`.

## Test-mode flow

With a test key, messages to anyone are only kept in the Otipi log (sandbox). Messages to your own numbers or emails really arrive once you confirm them with a code. Each account gets 5 free test SMS for life.

1. `add_test_recipient` with your number (`+9725XXXXXXXX`). A 6-digit code is sent to it.
2. The human reads the code on the device.
3. `confirm_test_recipient` with the number and the code.
4. `send_test_otp` now really delivers. The result states whether delivery was real or sandbox.
5. `verify_otp` with the code the human received (or the `test_code` returned in test mode).

## Tools

| Tool | What it does |
| --- | --- |
| `send_test_otp` | Send an OTP (sms or email). Reports real vs sandbox delivery and includes `test_code`. |
| `verify_otp` | Check a code for a recipient. |
| `add_test_recipient` | Start confirming a number or email as a test recipient. |
| `confirm_test_recipient` | Finish confirmation with the 6-digit code. |
| `list_test_recipients` | List recipients and the free test SMS left. |
| `check_delivery_status` | Look up a message and its event timeline. |
| `get_integration_snippet` | Offline, no key needed. Code for `nextjs`, `supabase` or `express` (`ts` or `js`). |

Tool failures are returned as normal results with `isError: true` and a plain explanation of what to do next.

## Security notes

- The API key lives in the environment only. It is never printed, logged or returned by any tool.
- Use free `sk_test_` keys for development. Do not put `sk_live_` keys into shared config files or repositories.
- Requests use a 15 second timeout, no redirects, and `Authorization: Bearer` over HTTPS.
- stdout carries only JSON-RPC messages; diagnostics go to stderr.

## Development

```
npm test
```

The tests spawn the server and drive it over stdio against a local fake Otipi API. No network access is needed.

## Publishing (for maintainers)

Not automated. Dmitry runs these by hand.

The GitHub owner is set to `planetebatel-cloud` in `package.json` (`mcpName`, `repository`) and `server.json` (`name`, `repository`). The `mcpName` must start with `io.github.<github-username>/` for GitHub login, so adjust all of these together if the repository lives under a different owner.

```
npm publish --access public
mcp-publisher login github
mcp-publisher publish
```

Keep `version` in `package.json` and `server.json` (both the top level and the package entry) identical on every release. `node scripts/validate-server-json.mjs <schema.json>` checks `server.json` against the schema from `https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json`.

## License

MIT

TDQS

A4.2/5.0

Scored across 7 tools

Disambiguation4/5

Each tool has a distinct role: sending vs verifying OTPs, recipient onboarding (add/confirm/list), delivery lookup, and code snippet retrieval. The only mild friction is that verify_otp and confirm_test_recipient both 'check a code', but the descriptions clearly separate end-user OTP verification from test-recipient confirmation.

Naming Consistency5/5

All names are snake_case and verb-first (verify_, send_, add_, confirm_, list_, check_, get_) with clear object nouns. The multi-word object forms (test_otp, test_recipient, delivery_status, integration_snippet) are used consistently.

Tool Count5/5

Seven tools is well-scoped for a test-mode OTP/integration workflow, with each tool earning its place across recipient setup, sending, verifying, status, and code snippets. No redundant or filler tools.

Completeness4/5

The surface covers the full test flow: recipient creation/confirmation/listing, OTP send and verify, delivery status, and integration snippets. Minor gaps exist — no way to remove or revoke a test recipient and no live-mode send tool — but agents can work around these.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues