Content
# IFTTT MCP Proxy
A local **stdio MCP server** that bridges [IFTTT's remote MCP endpoint](https://ifttt.com/mcp) to any MCP client that only supports the stdio transport (e.g., [Amazon Quick](https://amazon.com/quick), Claude Desktop, Cursor, etc.).
## The Problem
IFTTT exposes a remote MCP server at `https://ifttt.com/mcp` using:
- **OAuth 2.1 with PKCE** for authentication
- **Streamable HTTP** transport with **SSE (Server-Sent Events)** for streaming responses
Many MCP clients (including Amazon Quick and Claude Desktop) only support **stdio** transport — they launch a local process and communicate via stdin/stdout. They cannot directly connect to remote HTTP MCP servers that require OAuth redirect flows.
## The Solution
This proxy runs as a local Node.js process that:
1. **Handles OAuth 2.1 + PKCE** — one-time browser-based authentication flow with automatic token refresh
2. **Bridges stdio ↔ HTTP** — reads JSON-RPC messages from stdin, forwards them to IFTTT's remote endpoint, and writes responses to stdout
3. **Handles SSE streaming** — IFTTT responds to tool calls with HTTP 202 + SSE streams; the proxy keeps the connection open and collects the full response before writing it to stdout
4. **Transforms responses** — IFTTT returns data in `structuredContent` while standard MCP clients expect it in `content[]`; the proxy normalizes this automatically
5. **Auto-refreshes tokens** — detects expired tokens and uses the refresh token to obtain new access tokens transparently
## Architecture
```
┌─────────────┐ stdio ┌──────────────────┐ HTTPS/SSE ┌─────────────┐
│ MCP Client │ ──stdin/stdout──│ ifttt-mcp-proxy │ ───────────────│ ifttt.com/ │
│ (e.g. │ │ │ │ mcp │
│ Amazon │ │ • OAuth token │ │ │
│ Quick) │ │ • SSE handling │ │ (Remote │
│ │ │ • Response │ │ MCP │
│ │ │ transform │ │ Server) │
└─────────────┘ └──────────────────┘ └─────────────┘
```
## Installation
```bash
git clone https://github.com/maishsk/ifttt-mcp-proxy.git
cd ifttt-mcp-proxy
```
No dependencies required — uses only Node.js built-in modules (`http`, `https`, `crypto`, `fs`, `path`, `url`, `child_process`).
**Requirements:** Node.js 18+
## Usage
### 1. Authenticate (one-time)
```bash
node index.js --auth
```
This opens your browser for the IFTTT OAuth flow. After authorizing, the token is saved to `~/.quickwork/ifttt-token.json` (with `0600` permissions).
### 2. Check Token Status
```bash
node index.js --status
```
Shows whether your token is valid, when it was obtained, and when it expires.
### 3. Run as MCP Proxy
```bash
node index.js
```
Starts in stdio mode — reads JSON-RPC from stdin, proxies to IFTTT, writes responses to stdout. Diagnostic logs go to stderr.
### 4. Configure in Your MCP Client
Add to your MCP client configuration:
```json
{
"mcpServers": {
"ifttt": {
"command": "node",
"args": ["/path/to/ifttt-mcp-proxy/index.js"]
}
}
}
```
Or use the included wrapper script that handles first-run auth automatically:
```json
{
"mcpServers": {
"ifttt": {
"command": "bash",
"args": ["/path/to/ifttt-mcp-proxy/start.sh"]
}
}
}
```
## How It Works
### OAuth 2.1 + PKCE Flow
1. Generates a PKCE code verifier/challenge pair
2. Opens browser to `https://ifttt.com/oauth/authorize` with the challenge
3. Spins up a temporary HTTP server on `localhost:3118` to receive the callback
4. Exchanges the authorization code for an access token + refresh token
5. Saves tokens to `~/.quickwork/ifttt-token.json`
### Streamable HTTP + SSE Handling
IFTTT's MCP server uses the **Streamable HTTP** MCP transport:
- Simple requests (like `initialize`, `tools/list`) return direct JSON responses
- Tool calls (`tools/call`) may return HTTP 200/202 with `Content-Type: text/event-stream`
- The SSE stream contains `data:` lines with the actual JSON-RPC response
The proxy handles all three response types:
- **Direct JSON** (200 + `application/json`) → parsed and forwarded
- **SSE stream** (200/202 + `text/event-stream`) → collected until stream ends, events parsed and forwarded
- **Error responses** (4xx/5xx) → converted to JSON-RPC error objects
### Response Transformation
IFTTT puts tool results in a non-standard `structuredContent` field while leaving the standard `content` array empty. The proxy detects this and moves the data into `content[{type: "text", text: ...}]` for compatibility.
### Token Auto-Refresh
On every request, the proxy checks token expiry (with a 60-second buffer). If expired, it uses the refresh token to obtain a new access token before proceeding. If a request returns HTTP 401, it attempts a refresh and retries once.
## Files
| File | Description |
|------|-------------|
| `index.js` | Main proxy server (OAuth + stdio proxy) |
| `package.json` | Package metadata |
| `start.sh` | Wrapper script with auto-auth on first run |
## Token Storage
Tokens are stored at `~/.quickwork/ifttt-token.json` with file permissions `0600` (owner read/write only). The file contains:
- `access_token` — Bearer token for IFTTT API
- `refresh_token` — Used to obtain new access tokens
- `expires_in` — Token lifetime in seconds
- `obtained_at` — Timestamp when the token was obtained
## Troubleshooting
### "No token found"
Run `node index.js --auth` to complete the OAuth flow.
### "Token refresh failed"
Your refresh token may have been revoked. Re-run `node index.js --auth`.
### Empty responses from tool calls
This usually means the SSE stream wasn't properly consumed. Check stderr logs for details. The proxy handles the common IFTTT pattern of 202 + SSE.
### Port 3118 in use
The OAuth callback uses port 3118. If it's occupied, kill the process using it or wait for it to release.
## License
MIT
