Samotpravil MCP

Name: Samotpravil MCP
Author: dkanster

本地服务

github.com通信协作07 周前更新

代码仓库访问官网

关于 Samotpravil MCP

Samotpravil MCP 将 Agent 接入 Samotpravil API 及其文档，结合可搜索的 API 文档、类型化工具、Python SDK 对应工具，以及可配置的邮件和账户操作安全限制。

主要功能

01搜索 API 文档和端点
02提供类型化 API 工具
03提供与 Python SDK 对应的工具
04支持只读和 dry_run 安全限制
05以资源和提示词提供 API 文档

适用场景

01集成前查询 API 方法
02发送邮件并检查投递状态
03管理停用名单和允许域名
04预览或限制 API 修改

MCP 相关

该服务向 MCP 客户端提供文档、类型化 API 工具、资源和提示词。API 操作需要 `SAMOTPRAVIL_API_KEY`，文档工具则不需要。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "dkanster-samotpravil": {
      "command": "npx",
      "args": [
        "-y",
        "samotpravil-mcp"
      ],
      "env": {
        "SAMOTPRAVIL_API_KEY": "<SAMOTPRAVIL_API_KEY>",
        "SAMOTPRAVIL_READ_ONLY": "<SAMOTPRAVIL_READ_ONLY>",
        "SAMOTPRAVIL_ALLOW_SEND": "<SAMOTPRAVIL_ALLOW_SEND>",
        "SAMOTPRAVIL_ALLOW_MUTATIONS": "<SAMOTPRAVIL_ALLOW_MUTATIONS>",
        "SAMOTPRAVIL_ALLOW_GENERIC_API": "<SAMOTPRAVIL_ALLOW_GENERIC_API>",
        "SAMOTPRAVIL_HTTP_HOST": "<SAMOTPRAVIL_HTTP_HOST>",
        "POSTMAN_API_KEY": "<POSTMAN_API_KEY>",
        "POSTMAN_COLLECTION_UID": "<POSTMAN_COLLECTION_UID>",
        "SAMOTPRAVIL_HTTP_AUTH_TOKEN": "<SAMOTPRAVIL_HTTP_AUTH_TOKEN>",
        "SAMOTPRAVIL_HTTP_PORT": "<SAMOTPRAVIL_HTTP_PORT>",
        "SAMOTPRAVIL_DOCS_MODE": "<SAMOTPRAVIL_DOCS_MODE>"
      }
    }
  }
}

启动命令npx -y samotpravil-mcp

需要配置的环境变量

SAMOTPRAVIL_API_KEY密钥API key for api.samotpravil.ru (Authorization header)

SAMOTPRAVIL_READ_ONLYWhen true, block mutating HTTP methods except GET/HEAD

SAMOTPRAVIL_ALLOW_SENDWhen false, block send/package endpoints

SAMOTPRAVIL_ALLOW_MUTATIONSWhen false, block stop-list, domain, authkey and other mutating endpoints

SAMOTPRAVIL_ALLOW_GENERIC_APIWhen false, disable the generic api_request tool

SAMOTPRAVIL_HTTP_HOSTBind address for --http transport (default 127.0.0.1)

POSTMAN_API_KEY密钥Postman API key for maintainer tools (postman_get_collection, postman_sync_snapshot, …)

POSTMAN_COLLECTION_UIDPostman collection UID for documentation (default 2s93RZM9in)

SAMOTPRAVIL_HTTP_AUTH_TOKEN密钥Bearer token required for HTTP transport when exposed beyond localhost

SAMOTPRAVIL_HTTP_PORTPort for --http transport (default 3000)

SAMOTPRAVIL_DOCS_MODEDocumentation source: auto | live | snapshot

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmsamotpravil-mcp1.8.0stdio

工具

收录的工具列表 · 更新于 2 周前

此工具无需参数。

README 原文English

来自项目 README

README 暂无中文译文，以下为英文原文；中文介绍见上方。

Samotpravil MCP

MCP-сервер вокруг документации API СамОтправил и HTTP API api.samotpravil.ru.

Версия: 1.8.0 · npm: samotpravil-mcp · MCP Registry: io.github.dkanster/samotpravil-api-mcp · Smithery: smithery.yaml · Cursor Directory: .mcp.json

Хостинг: репозиторий временно в dkanster/samotpravil-api-mcp.
Планируется: переезд в org Samotpravil → @samotpravil/mcp — docs/ORG_MIGRATION.md.

Сервер подтягивает Postman-коллекцию с documenter (live + offline snapshot) и даёт агенту tools для поиска методов, вызова API и безопасных пресетов (READ_ONLY, dry_run). Имена typed tools совпадают с Python SDK samotpravil.

Экосистема: Postman → snapshot → MCP / OpenAPI / Docusaurus — docs/ECOSYSTEM.md · live preview: https://dkanster.github.io/samotpravil-api-mcp/

Быстрый старт

npx -y samotpravil-mcp@latest

Cursor — .cursor/mcp.json:

{
  "mcpServers": {
    "samotpravil": {
      "command": "npx",
      "args": ["-y", "samotpravil-mcp@latest"],
      "env": {
        "SAMOTPRAVIL_API_KEY": "your_api_key_here",
        "SAMOTPRAVIL_READ_ONLY": "1",
        "SAMOTPRAVIL_ALLOW_SEND": "0"
      }
    }
  }
}

SAMOTPRAVIL_API_KEY опционален для docs-only tools. После правок: Settings → MCP → Reload.

Бесплатного тестового ключа нет: регистрация в ЛК → верификация домена отправителя → ключ в env. Пакетную боевую отправку по умолчанию не открываем (SAMOTPRAVIL_ALLOW_SEND=0).

Экосистема (рядом с MCP)

Артефакт	Ссылка
Спека OpenAPI	https://spec.samotpravil.ru/openapi.yaml
Node-клиент API	`npm i samotpravil`
Пример SaaS (два ключа TX/MKT)	dkanster/samotpravil-example
Python MCP (pip)	`mailganer-samotpravil-mcp`
Smithery	daniil-kozemiakin/samotpravil
Cursor Directory	samotpravil-api-mcp

Для SaaS сразу два API-ключа (разные стоп-листы и webhook URL) — см. пример выше.

Сценарии и конфиги для Claude / VS Code: docs/EXAMPLES.md

Cursor Directory

Каталог сообщества cursor.directory автодетектит MCP из корневого .mcp.json (дубль: mcp.json, манифест plugin.json). Первая отправка: cursor.directory/plugins/new → URL этого репозитория (вход GitHub/Google). В листинг не входят swagger-mcp и Postman maintainer.

Дальше править код и карточку — docs/PUBLISH.md § «Cursor Directory»: релиз npm по tag v*; карточку Directory не слать второй раз (дубли). Add to Cursor у уже поставивших сам не обновляется.

Что внутри

Компонент	Кол-во	Нужен ключ
Docs tools	4	нет
Core typed API	9 + `api_request`	`SAMOTPRAVIL_API_KEY`
Python SDK parity	28	`SAMOTPRAVIL_API_KEY`
Auto tools (`api_*`)	~16	`SAMOTPRAVIL_API_KEY`
Postman maintainer	4	`POSTMAN_API_KEY`
MCP Resources	9	нет
MCP Prompts	5	нет

Итого: ~59 tools ( +4 postman при POSTMAN_API_KEY).

Инструменты

Документация (без API-ключа)

Tool	Описание
`get_overview`	Авторизация, SMTP, лимиты, категории
`list_endpoints`	Список всех методов API
`search_docs`	Поиск по документации
`get_endpoint`	Подробности по методу

Typed API (нужен `SAMOTPRAVIL_API_KEY`)

Tool	Описание
`send_email`	POST `/api/v1/smtp_send`
`send_mail_v2`	POST `/api/v2/mail/send`
`get_delivery_status`	GET `/api/v2/issue/status` (`message_id` или `x_track_id`)
`get_package_status`	GET `/api/v2/package/status`
`search_stop_list`	Поиск email в стоп-листах
`add_stop_list_email` / `remove_stop_list_email`	Стоп-лист (`mail_from` или `domain`)
`validate_email`	POST `/api/v2/emails/validate/`
`list_allowed_domains`	GET `/api/v2/blist/domains`
`api_request`	Generic escape hatch

Python SDK parity (v1.3+)

Typed tools с именами как в PyPI-пакете samotpravil: send_package, get_statistics, get_ext_status, stop_list_export_create, domain_add, get_blist, create_authkey и др.

Полный список и маппинг: docs/EXAMPLES.md#python-sdk-parity · prompt python_sdk_parity

Postman maintainer (нужен `POSTMAN_API_KEY`)

Tool	Описание
`postman_get_collection`	Коллекция из Postman API
`postman_sync_snapshot`	Postman API → `data/collection.snapshot.json`
`postman_diff_snapshot`	Diff Postman vs локальный snapshot
`postman_search_requests`	Поиск запросов в коллекции

Подробнее: docs/EXAMPLES.md#postman-tools

Auto tools

api_{method}_{path} — для HTTP-методов, не покрытых typed tools (legacy v1, tickets, email check/clean и т.д.).

MCP Prompts

Prompt	Описание
`integration_overview`	Обзор SMTP + HTTP + лимиты
`send_transactional`	Чеклист отправки письма
`stop_list_workflow`	Работа со стоп-листами
`check_delivery`	Статус по X-Track-ID / выпуску
`python_sdk_parity`	Python SDK → MCP tools

MCP Resources

URI	Содержимое
`samotpravil://overview`	Обзор API
`samotpravil://endpoints`	Индекс методов
`samotpravil://endpoint/{slug}`	Один метод
`samotpravil://errors`	Популярные ошибки
`samotpravil://integration`	SMTP, X-Track-ID, трекинг
`samotpravil://sdk-mapping`	Python SDK → MCP tools
`samotpravil://changelog`	Фрагмент CHANGELOG пакета
`samotpravil://rate-limits`	Лимиты API и отправки
`samotpravil://api-wishlist`	Предложения по HTTP API (фрагмент)

Безопасность

Env	Эффект
`SAMOTPRAVIL_READ_ONLY=1`	Только GET/HEAD
`SAMOTPRAVIL_ALLOW_SEND=0`	Блок send/package
`SAMOTPRAVIL_ALLOW_MUTATIONS=0`	Блок stop-list, доменов, authkey
`SAMOTPRAVIL_ALLOW_GENERIC_API=0`	Отключить `api_request`
`SAMOTPRAVIL_DOCS_MODE`	`auto` \| `live` \| `snapshot`
`dry_run: true`	Preview запроса без отправки

Секреты (api_key, key= в query) маскируются в ответах MCP.

Транспорты и интеграции

HTTP transport

npx samotpravil-mcp --http --port 3000
# POST http://127.0.0.1:3000/mcp

Env: SAMOTPRAVIL_HTTP_HOST, SAMOTPRAVIL_HTTP_PORT, SAMOTPRAVIL_HTTP_AUTH_TOKEN, SAMOTPRAVIL_HTTP_JSON_LOG=1 (structured logs).

docker build -t samotpravil-mcp .
docker run --rm -p 3000:3000 -e SAMOTPRAVIL_API_KEY=... -e SAMOTPRAVIL_HTTP_AUTH_TOKEN=... samotpravil-mcp

OpenAPI + Swagger-MCP

npm run export-openapi        # → data/openapi.yaml
npm run upload-swaggerhub     # SwaggerHub (нужен .env.swaggerhub)
npm run prepare-swagger-mcp   # Vizioz/Swagger-MCP

Спека: mailganer/[email protected] · docs/SWAGGERHUB.md

Docusaurus preview

npm run docusaurus:install && npm run docusaurus:start

Live: https://dkanster.github.io/samotpravil-api-mcp/ · docs/DOCS_SITE.md

Discovery

Площадка	Ссылка
npm	https://www.npmjs.com/package/samotpravil-mcp
MCP Registry	https://registry.modelcontextprotocol.io
Smithery	`smithery.yaml` в корне — docs/PUBLISH.md
Официальный promo	docs/official/

Конфигурация

Шаблон: .env.samotpravil.example

SAMOTPRAVIL_API_KEY=your_key_here
# POSTMAN_API_KEY=...          # maintainer tools
# SAMOTPRAVIL_READ_ONLY=1

Ключ API: https://samotpravil.ru/get-access

Полный список env: docs/EXAMPLES.md

Разработка

git clone https://github.com/dkanster/samotpravil-api-mcp.git
cd samotpravil-api-mcp
npm install && npm test && npm run dev
npm run setup-hooks   # optional: pre-commit (lint + test)
npm run lint          # ESLint
npm run pre-publish-check   # перед npm tag
npm run release-prepare      # pre-flight перед npm tag
npm run generate-tool-catalog
npm run scaffold-typed-tool send_package

Security: SECURITY.md
Contributing: CONTRIBUTING.md
Changelog: CHANGELOG.md
Publish: docs/PUBLISH.md
Roadmap: docs/ROADMAP_v1.6.md · Release: docs/RELEASE_v1.7.0.md
Org migration: docs/ORG_MIGRATION_RUNBOOK.md · npm run plan-org-migration
API v1→v2: docs/MIGRATION_V1_TO_V2.md
API wishlist (предложения для HTTP API продукта): docs/API_WISHLIST.md

Источник документации

Live: https://documentation.samotpravil.ru/
Offline: data/collection.snapshot.json
Обновить: npm run sync-docs или postman_sync_snapshot
API: https://api.samotpravil.ru · SMTP: api.samotpravil.ru:1126 / :1127

Из git clone в свой проект

/path/to/samotpravil-api-mcp/setup.sh .

Лицензия

MIT

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

Samotpravil MCP

关于 Samotpravil MCP

主要功能

适用场景

MCP 相关

配置

工具

README 原文English

Samotpravil MCP

Быстрый старт

Экосистема (рядом с MCP)

Cursor Directory

Что внутри

Инструменты

Документация (без API-ключа)

Typed API (нужен SAMOTPRAVIL_API_KEY)

Python SDK parity (v1.3+)

Postman maintainer (нужен POSTMAN_API_KEY)

Auto tools

MCP Prompts

MCP Resources

Безопасность

Транспорты и интеграции

HTTP transport

OpenAPI + Swagger-MCP

Docusaurus preview

Discovery

Конфигурация

Разработка

Источник документации

Из git clone в свой проект

Лицензия

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？

Typed API (нужен `SAMOTPRAVIL_API_KEY`)

Postman maintainer (нужен `POSTMAN_API_KEY`)