@useblip/email 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2026 bmcreations
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published
+by the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.

package/README.md

@@ -0,0 +1,78 @@
+# @useblip/email
+
+MCP server for [Blip](https://useblip.email) disposable email. Create inboxes, receive emails, and extract OTP codes — all from your AI agent.
+
+## Setup
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "blip": {
+      "command": "npx",
+      "args": ["-y", "@useblip/email"],
+      "env": {
+        "BLIP_API_KEY": "blip_ak_..."
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add blip -- npx -y @useblip/email
+```
+
+Set your API key:
+
+```bash
+export BLIP_API_KEY=blip_ak_...
+```
+
+### Other MCP clients
+
+Run the server directly:
+
+```bash
+BLIP_API_KEY=blip_ak_... npx @useblip/email
+```
+
+## Getting an API key
+
+1. Sign in at [app.useblip.email](https://app.useblip.email)
+2. Subscribe to the **Agent** tier
+3. Create an API key from the dashboard
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_inbox` | Create a disposable email inbox with optional custom slug, domain, and TTL |
+| `list_inboxes` | List all active inboxes |
+| `get_inbox` | Get inbox details and list of received emails |
+| `read_email` | Read full email content (body, headers, attachments) |
+| `extract_codes` | Extract OTP codes and verification links from the latest email |
+| `wait_for_email` | Poll until an email arrives (configurable timeout, default 60s) |
+| `delete_inbox` | Delete an inbox and all its emails |
+
+## Example prompts
+
+- "Create a disposable email and sign up for example.com, then give me the verification code"
+- "Make an inbox, wait for the password reset email, and extract the link"
+- "List my active inboxes and show me the latest emails"
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BLIP_API_KEY` | Yes | — | Your Blip API key |
+| `BLIP_API_URL` | No | `https://api.useblip.email` | API base URL (for self-hosted) |
+
+## License
+
+AGPL-3.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const API_URL = process.env.BLIP_API_URL || "https://api.useblip.email";
+const API_KEY = process.env.BLIP_API_KEY || "";
+if (!API_KEY) {
+    console.error("BLIP_API_KEY is required. Create one at https://useblip.email/app");
+    process.exit(1);
+}
+async function blipFetch(path, options = {}) {
+    const url = `${API_URL}${path}`;
+    const res = await fetch(url, {
+        ...options,
+        headers: {
+            Authorization: `Bearer ${API_KEY}`,
+            "Content-Type": "application/json",
+            ...options.headers,
+        },
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Blip API error ${res.status}: ${body}`);
+    }
+    if (res.status === 204)
+        return null;
+    return res.json();
+}
+const server = new McpServer({
+    name: "blip",
+    version: "0.1.0",
+});
+// --- Tools ---
+server.tool("create_inbox", "Create a new disposable email inbox. Returns the inbox ID and email address.", {
+    slug: z
+        .string()
+        .optional()
+        .describe("Custom address slug (e.g. 'mytest' for mytest@useblip.email)"),
+    domain: z
+        .string()
+        .optional()
+        .describe("Email domain (defaults to useblip.email)"),
+    ttl_minutes: z
+        .number()
+        .optional()
+        .describe("How long the inbox should live, in minutes (AGENT tier only, max 90 days). Defaults to 60 minutes if omitted."),
+}, async ({ slug, domain, ttl_minutes }) => {
+    const body = {};
+    if (slug)
+        body.slug = slug;
+    if (domain)
+        body.domain = domain;
+    if (ttl_minutes !== undefined)
+        body.windowMinutes = ttl_minutes;
+    const result = await blipFetch("/v1/inboxes", {
+        method: "POST",
+        body: JSON.stringify(body),
+    });
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("list_inboxes", "List all active inboxes for the current API key.", {}, async () => {
+    const result = await blipFetch("/v1/inboxes");
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("get_inbox", "Get inbox details and list of received emails.", {
+    inbox_id: z.string().describe("The inbox ID"),
+}, async ({ inbox_id }) => {
+    const result = await blipFetch(`/v1/inboxes/${inbox_id}`);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("read_email", "Read the full content of a specific email including body, headers, and attachments.", {
+    email_id: z.string().describe("The email ID to read"),
+}, async ({ email_id }) => {
+    const result = await blipFetch(`/v1/emails/${email_id}`);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("extract_codes", "Extract OTP codes and verification links from the most recent email in an inbox. Use this after creating an inbox and receiving a verification/signup email.", {
+    inbox_id: z
+        .string()
+        .describe("The inbox ID to extract codes from (uses most recent email)"),
+}, async ({ inbox_id }) => {
+    const result = await blipFetch(`/v1/inboxes/${inbox_id}/extract`);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("wait_for_email", "Poll an inbox until an email arrives. Returns the email once received. Times out after the specified duration.", {
+    inbox_id: z.string().describe("The inbox ID to wait on"),
+    timeout_seconds: z
+        .number()
+        .optional()
+        .describe("Max seconds to wait (default: 60, max: 300)"),
+}, async ({ inbox_id, timeout_seconds }) => {
+    const timeout = Math.min(timeout_seconds ?? 60, 300);
+    const deadline = Date.now() + timeout * 1000;
+    const interval = 2000;
+    while (Date.now() < deadline) {
+        const result = (await blipFetch(`/v1/inboxes/${inbox_id}`));
+        if (result?.emails && result.emails.length > 0) {
+            // Return the full detail of the most recent email
+            const email = await blipFetch(`/v1/emails/${result.emails[0].id}`);
+            return {
+                content: [{ type: "text", text: JSON.stringify(email, null, 2) }],
+            };
+        }
+        await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `No email received in inbox ${inbox_id} after ${timeout} seconds.`,
+            },
+        ],
+    };
+});
+server.tool("delete_inbox", "Delete an inbox and all its emails.", {
+    inbox_id: z.string().describe("The inbox ID to delete"),
+}, async ({ inbox_id }) => {
+    await blipFetch(`/v1/inboxes/${inbox_id}`, { method: "DELETE" });
+    return {
+        content: [{ type: "text", text: `Inbox ${inbox_id} deleted.` }],
+    };
+});
+// --- Start ---
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@useblip/email",
+  "version": "0.1.0",
+  "description": "MCP server for Blip disposable email — create inboxes, receive emails, extract OTP codes",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "blip-email": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  },
+  "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blipemail/blip"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "email",
+    "disposable-email",
+    "temporary-email",
+    "otp",
+    "verification",
+    "ai-agent",
+    "claude",
+    "cursor",
+    "blip"
+  ]
+}