Metadata-Version: 2.5
Name: sendsoon-mcp
Version: 0.1.2
Summary: MCP server for SendSoon: send email, look up public IP information, and convert files to Markdown from Claude, Cursor, Codex, and other AI agents.
Project-URL: Homepage, https://github.com/sendsoon/ai
Project-URL: Documentation, https://github.com/sendsoon/ai/tree/main/python
Project-URL: Repository, https://github.com/sendsoon/ai
Project-URL: Issues, https://github.com/sendsoon/ai/issues
Author: SendSoon
License: MIT
License-File: LICENSE
Keywords: claude,codex,cursor,email,ip-lookup,markitdown,mcp,mcp-server,model-context-protocol,sendsoon
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.2.0
Provides-Extra: dev
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-httpx>=0.35; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# sendsoon-mcp

MCP server for [SendSoon](https://www.sendsoonai.com/). Gives Claude, Cursor, Codex, and other MCP clients the ability to send email, look up public IP information, and convert files to Markdown.

**PyPI:** [`sendsoon-mcp`](https://pypi.org/project/sendsoon-mcp/)  
**Server name:** `sendsoon`  
**Transport:** `stdio`  
**Tools:** `send_email`, `ip_lookup`, `markitdown_convert`  

Python package version is managed independently from the Node package [`@sendsoon/ai`](https://www.npmjs.com/package/@sendsoon/ai). Tool names and request/response semantics stay aligned.

---

## Install

Recommended (no global install):

```bash
uvx sendsoon-mcp
```

Or install the CLI:

```bash
pip install sendsoon-mcp
sendsoon-mcp
```

**Requirements:** Python 3.10+, and a client that supports local stdio MCP servers.

---

## Configuration

| Variable | Required | Description |
| --- | --- | --- |
| `SENDSOON_EMAIL_RECIPIENT` | **Yes** | The **only** recipient address allowed for `send_email`. The `to` parameter must match this value exactly (case-insensitive). |
| `SENDSOON_API_KEY` | No | Leave empty for anonymous trial: one public IP may send up to **3 test emails per day**. After that, register at [sendsoonai.com](https://sendsoonai.com/login-register), generate a `ssk_live_...` Key at [Profile](https://www.sendsoonai.com/profile), and set it here. |
| `SENDSOON_API_BASE_URL` | No | Defaults to `https://www.sendsoonai.com`. HTTPS required except `http://localhost`. |

Never commit a real Key to Git or share it with anyone.

Invalid or revoked Keys are rejected and do **not** fall back to the anonymous quota.

---

## Client configuration

### Cursor / Claude Desktop

```json
{
  "mcpServers": {
    "sendsoon": {
      "command": "uvx",
      "args": ["sendsoon-mcp"],
      "env": {
        "SENDSOON_EMAIL_RECIPIENT": "<YOUR_EMAIL>",
        "SENDSOON_API_KEY": ""
      }
    }
  }
}
```

After `pip install sendsoon-mcp`, you can use `"command": "sendsoon-mcp"` with an empty `args` array (or omit `args`).

### Codex

```toml
[mcp_servers.sendsoon]
command = "uvx"
args = ["sendsoon-mcp"]

[mcp_servers.sendsoon.env]
SENDSOON_EMAIL_RECIPIENT = "<YOUR_EMAIL>"
SENDSOON_API_KEY = ""
```

### Claude Code

```powershell
claude mcp add --transport stdio --scope user --env SENDSOON_EMAIL_RECIPIENT=<YOUR_EMAIL> sendsoon -- uvx sendsoon-mcp
```

---

## Tools

| Tool | Input highlights | Notes |
| --- | --- | --- |
| `send_email` | `to`, `subject`, `body`, optional `content_type`, `idempotency_key` | Recipient must match `SENDSOON_EMAIL_RECIPIENT` |
| `ip_lookup` | `ip` | Public IPv4/IPv6 only |
| `markitdown_convert` | `filename`, `content_base64` | Remote SendSoon conversion (max 10 MB decoded); same semantics as the Node MCP |

---

## Development

```bash
cd python
python -m pip install -e ".[dev]"
pytest
ruff check src tests
mypy
```

---

## License

MIT — see [LICENSE](LICENSE).
