tmailor-mcp 0.1.0__tar.gz

tmailor_mcp-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+# local secrets / env
+.env
+*.key

tmailor_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0 (2026-10-20)
+
+- First version: stdio MCP server with the tools `create_mailbox`, `wait_for_message`, `list_messages`,
+  `read_message`, `delete_mailbox`, `list_mailboxes`, `list_domains` and `account_status`, built on `tmailor-sdk`.

tmailor_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tmailor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tmailor_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.5
+Name: tmailor-mcp
+Version: 0.1.0
+Summary: MCP server for the Tmailor Open API: temporary email addresses and OTP codes for AI agents.
+Project-URL: Homepage, https://platform.tmailor.com
+Project-URL: Documentation, https://platform.tmailor.com/docs
+Project-URL: Source, https://github.com/tmailor-com/tmailor-mcp
+Project-URL: Support, https://tmailor.com/contact-us
+Author: Tmailor
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai agent,email testing,mcp,model context protocol,otp,temp mail,temporary email,tmailor
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: tmailor-sdk<1,>=0.2.0
+Requires-Dist: typing-extensions>=4.7
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tmailor-mcp
+
+MCP server for the [Tmailor Open API](https://platform.tmailor.com/docs). It gives AI agents (Claude, Cursor,
+VS Code Copilot and any other MCP client) real, receive-only temporary email addresses: sign up somewhere, wait for
+the email, get the one-time code or the verification link.
+
+```text
+You:   Sign up on example.com with a temporary email and confirm the account.
+Agent: create_mailbox -> k3x9q2m7@picdirect.net
+       (fills in the sign-up form)
+       wait_for_message -> otp "482913", links ["https://example.com/confirm?t=..."]
+```
+
+Billing counts mailboxes, not requests: creating an address uses 1 unit of quota, while waiting for and reading
+mail is free. Addresses never expire.
+
+## Requirements
+
+- A Tmailor API key: sign in at https://platform.tmailor.com and create one under **API keys**.
+- [uv](https://docs.astral.sh/uv/) (for `uvx`) or Python 3.10+.
+- On the **Free plan** the API only accepts calls from your allowlisted IP: add the public IP of the computer that
+  runs the MCP server under **IP allowlist**. Paid plans accept calls from any IP.
+
+## Install
+
+The server runs locally over stdio. The API key is read from the `TMAILOR_API_KEY` environment variable.
+
+### Claude Code
+
+```bash
+claude mcp add tmailor -e TMAILOR_API_KEY=tmk_live_... -- uvx tmailor-mcp
+```
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (Settings > Developer > Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "tmailor": {
+      "command": "uvx",
+      "args": ["tmailor-mcp"],
+      "env": { "TMAILOR_API_KEY": "tmk_live_..." }
+    }
+  }
+}
+```
+
+### Cursor
+
+`~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project) uses the same `mcpServers` block as above.
+
+### VS Code
+
+`.vscode/mcp.json`. The key is asked once and stored by VS Code instead of being written in the file:
+
+```json
+{
+  "inputs": [
+    { "type": "promptString", "id": "tmailor-key", "description": "Tmailor API key", "password": true }
+  ],
+  "servers": {
+    "tmailor": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["tmailor-mcp"],
+      "env": { "TMAILOR_API_KEY": "${input:tmailor-key}" }
+    }
+  }
+}
+```
+
+### Without uv
+
+```bash
+pip install tmailor-mcp
+TMAILOR_API_KEY=tmk_live_... tmailor-mcp
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `create_mailbox` | Create an address (random on a shared domain, or a chosen name on your own verified domain). Uses 1 quota unit. |
+| `wait_for_message` | Return the newest unread message matching optional sender/subject filters, or wait for one (up to 300 s). Includes `otp`, `codes`, `links` and the text. |
+| `list_messages` | Messages of an address (last 24 hours), without body. |
+| `read_message` | One message with `otp`, `codes`, `links` and text. |
+| `delete_mailbox` | Delete an address for good. Quota is not returned. |
+| `list_mailboxes` | Your addresses, newest first. |
+| `list_domains` | Your own domains and whether shared domains are available. |
+| `account_status` | Remaining quota, plans, request rate. |
+
+Tools take and return **email addresses only**. The address tokens of the API stay inside the server process, so
+they never end up in the conversation.
+
+## Security notes
+
+- **Email content is untrusted.** Anyone can send mail to an address. The server returns plain text only (no HTML),
+  cuts it to `max_chars`, and marks every message with `untrusted_content_notice`. Agents should use mail as data
+  (codes, links) and never follow instructions written inside it.
+- **Keep the key out of shared files.** Prefer the VS Code `inputs` prompt, or a user-level config file that is
+  not committed to a repository. Revoke a leaked key at https://platform.tmailor.com/keys.
+- Paid plans accept API calls from any IP, so a leaked key can be used from anywhere until you revoke it.
+- `wait_for_message` never returns the same message twice within one server process. Two MCP servers waiting on the
+  same address at the same time (for example two agents sharing one key) can both receive the same message.
+
+## Configuration
+
+| Variable | Meaning |
+|---|---|
+| `TMAILOR_API_KEY` | Your API key (required). |
+| `TMAILOR_BASE_URL` | Only for testing against another API host. |
+
+## Links
+
+- API reference: https://platform.tmailor.com/docs
+- Python SDK used by this server: [`tmailor-sdk`](https://pypi.org/project/tmailor-sdk/)
+- Plans: https://platform.tmailor.com/plans
+
+## License
+
+MIT

tmailor_mcp-0.1.0/README.md

@@ -0,0 +1,123 @@
+# tmailor-mcp
+
+MCP server for the [Tmailor Open API](https://platform.tmailor.com/docs). It gives AI agents (Claude, Cursor,
+VS Code Copilot and any other MCP client) real, receive-only temporary email addresses: sign up somewhere, wait for
+the email, get the one-time code or the verification link.
+
+```text
+You:   Sign up on example.com with a temporary email and confirm the account.
+Agent: create_mailbox -> k3x9q2m7@picdirect.net
+       (fills in the sign-up form)
+       wait_for_message -> otp "482913", links ["https://example.com/confirm?t=..."]
+```
+
+Billing counts mailboxes, not requests: creating an address uses 1 unit of quota, while waiting for and reading
+mail is free. Addresses never expire.
+
+## Requirements
+
+- A Tmailor API key: sign in at https://platform.tmailor.com and create one under **API keys**.
+- [uv](https://docs.astral.sh/uv/) (for `uvx`) or Python 3.10+.
+- On the **Free plan** the API only accepts calls from your allowlisted IP: add the public IP of the computer that
+  runs the MCP server under **IP allowlist**. Paid plans accept calls from any IP.
+
+## Install
+
+The server runs locally over stdio. The API key is read from the `TMAILOR_API_KEY` environment variable.
+
+### Claude Code
+
+```bash
+claude mcp add tmailor -e TMAILOR_API_KEY=tmk_live_... -- uvx tmailor-mcp
+```
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (Settings > Developer > Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "tmailor": {
+      "command": "uvx",
+      "args": ["tmailor-mcp"],
+      "env": { "TMAILOR_API_KEY": "tmk_live_..." }
+    }
+  }
+}
+```
+
+### Cursor
+
+`~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project) uses the same `mcpServers` block as above.
+
+### VS Code
+
+`.vscode/mcp.json`. The key is asked once and stored by VS Code instead of being written in the file:
+
+```json
+{
+  "inputs": [
+    { "type": "promptString", "id": "tmailor-key", "description": "Tmailor API key", "password": true }
+  ],
+  "servers": {
+    "tmailor": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["tmailor-mcp"],
+      "env": { "TMAILOR_API_KEY": "${input:tmailor-key}" }
+    }
+  }
+}
+```
+
+### Without uv
+
+```bash
+pip install tmailor-mcp
+TMAILOR_API_KEY=tmk_live_... tmailor-mcp
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `create_mailbox` | Create an address (random on a shared domain, or a chosen name on your own verified domain). Uses 1 quota unit. |
+| `wait_for_message` | Return the newest unread message matching optional sender/subject filters, or wait for one (up to 300 s). Includes `otp`, `codes`, `links` and the text. |
+| `list_messages` | Messages of an address (last 24 hours), without body. |
+| `read_message` | One message with `otp`, `codes`, `links` and text. |
+| `delete_mailbox` | Delete an address for good. Quota is not returned. |
+| `list_mailboxes` | Your addresses, newest first. |
+| `list_domains` | Your own domains and whether shared domains are available. |
+| `account_status` | Remaining quota, plans, request rate. |
+
+Tools take and return **email addresses only**. The address tokens of the API stay inside the server process, so
+they never end up in the conversation.
+
+## Security notes
+
+- **Email content is untrusted.** Anyone can send mail to an address. The server returns plain text only (no HTML),
+  cuts it to `max_chars`, and marks every message with `untrusted_content_notice`. Agents should use mail as data
+  (codes, links) and never follow instructions written inside it.
+- **Keep the key out of shared files.** Prefer the VS Code `inputs` prompt, or a user-level config file that is
+  not committed to a repository. Revoke a leaked key at https://platform.tmailor.com/keys.
+- Paid plans accept API calls from any IP, so a leaked key can be used from anywhere until you revoke it.
+- `wait_for_message` never returns the same message twice within one server process. Two MCP servers waiting on the
+  same address at the same time (for example two agents sharing one key) can both receive the same message.
+
+## Configuration
+
+| Variable | Meaning |
+|---|---|
+| `TMAILOR_API_KEY` | Your API key (required). |
+| `TMAILOR_BASE_URL` | Only for testing against another API host. |
+
+## Links
+
+- API reference: https://platform.tmailor.com/docs
+- Python SDK used by this server: [`tmailor-sdk`](https://pypi.org/project/tmailor-sdk/)
+- Plans: https://platform.tmailor.com/plans
+
+## License
+
+MIT

tmailor_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tmailor-mcp"
+dynamic = ["version"]
+description = "MCP server for the Tmailor Open API: temporary email addresses and OTP codes for AI agents."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Tmailor" }]
+keywords = ["mcp", "model context protocol", "tmailor", "temp mail", "temporary email", "otp", "ai agent", "email testing"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Email",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = ["mcp>=2.3,<3", "tmailor-sdk>=0.2.0,<1", "typing-extensions>=4.7"]
+
+[project.scripts]
+tmailor-mcp = "tmailor_mcp.__main__:main"
+
+[project.urls]
+Homepage = "https://platform.tmailor.com"
+Documentation = "https://platform.tmailor.com/docs"
+Source = "https://github.com/tmailor-com/tmailor-mcp"
+Support = "https://tmailor.com/contact-us"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-asyncio>=0.21", "ruff>=0.5", "build"]
+
+[tool.hatch.version]
+path = "src/tmailor_mcp/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tmailor_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/tmailor_mcp", "tests", "README.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "-p no:cacheprovider"
+
+[tool.ruff]
+line-length = 130
+target-version = "py310"
+src = ["src", "tests"]
+cache-dir = "/tmp/ruff-cache-tmailor-mcp"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "S", "SIM", "RUF"]
+ignore = ["UP006", "UP007", "UP035", "UP045"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101", "S105", "S106"]

tmailor_mcp-0.1.0/src/tmailor_mcp/__init__.py

@@ -0,0 +1,12 @@
+"""MCP server for the Tmailor Open API: temporary email addresses and OTP codes for AI agents."""
+
+from ._version import __version__
+from .server import build_server
+
+__all__ = ["__version__", "build_server", "main"]
+
+
+def main() -> None:
+    from .__main__ import main as _main
+
+    _main()

tmailor_mcp-0.1.0/src/tmailor_mcp/__main__.py

@@ -0,0 +1,29 @@
+"""Entry point: ``tmailor-mcp`` (stdio transport). The API key comes from ``TMAILOR_API_KEY``."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from ._version import __version__
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="tmailor-mcp",
+        description="MCP server (stdio) for the Tmailor Open API. Set TMAILOR_API_KEY before starting it.",
+    )
+    parser.add_argument("--version", action="version", version=f"tmailor-mcp {__version__}")
+    parser.parse_args(argv)
+    if not os.environ.get("TMAILOR_API_KEY", "").strip():
+        # stdout belongs to the MCP protocol: warnings go to stderr. The server still starts so the client can list
+        # the tools; every call then explains how to set the key.
+        print("tmailor-mcp: TMAILOR_API_KEY is not set; tool calls will fail until it is.", file=sys.stderr)
+    from .server import build_server
+
+    build_server().run("stdio")
+
+
+if __name__ == "__main__":
+    main()

tmailor_mcp-0.1.0/src/tmailor_mcp/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"