Content
MCP Server
blastengine official MCP server. [blastengine](https://blastengine.jp/) is a
transactional email, batch delivery, and delivery log confirmation service for
domestic use.
This server acts as a local stdio [MCP](https://modelcontextprotocol.io/) server,
allowing some blastengine API operations to be used from MCP-compatible AI clients.
Authentication information is kept within the local process and is not logged.
Sending tools are disabled by default.
## Main Features
- Transactional email sending (1 destination)
- Batch delivery (draft creation, destination registration, preview, immediate/scheduled confirmation)
- Bulk import of destinations from CSV files
- Delivery search and detailed retrieval
- Email delivery log search retrieval
- Usage confirmation and monthly)
- Sending tools by default (explicitly enabled with environment variables)
## Getting Started
### Requirements
- Node.js 22 LTS or higher
- blastengine account
### Preparing Your Account
An blastengine account is required for use. If you don't have one, please register
from the [free trial application form](https://app.engn.jp/be/order/request-form).
After registration, you can confirm your login ID and API key on the [management screen](https://app.engn.jp/be/admin### Installation (Manual Setup)
Clone the repository and build it:
```sh
npm install
npm run build
```
The stdio entry point `dist/index.js` will.
### MCP Client Configuration
Add the built entry point to client settings:
1. settings
2. Move to settings section
3. Add the following settings:
```json "mcpServers": {
"blastengine": "command": "node",
"args": ["/path/to/blastengine_mcp/dist/index.js"],
"env": {
"BLASTENGINE_LOGIN_ID": "...",
"BLASTENGINE_API_KEY": "...",
"ENGINE_ENABLE_SEND":",
"BLASTENGINE_ENABLE_BULK": "false",
"BLASTENGINESV_IMPORT": "false"
}
}
}
```
Authentication is recommended using `BL_LOGIN_ID` and `ENGINE_API_KEY`.
The server generates a Bearer token locally (SHA-256 of `login_id + api_key` in lowercase hex and Base64)
and does not output it to logs. A generated `BLASTENGINE_BEARER_TOKEN` can also be used,
and it takes precedence when set. Do not commit authentication information to the repository or `.env`.
## Functional Modes (Enabling Sending)
The server starts in read-only mode. Email sending is irreversible (risk of misdelivery),
so sending disabled by default and can only be enabled by setting the corresponding environment variables to `true`.
- `BLASTENGINE_ENABLE_SEND` … Required for transactional sending
- `BLASTENGINE_ENABLE_BULK` … Required for batch delivery
- `BLASTENGINE_ENABLE_CSV_IMPORT` … Required for CSV destination import
Read-only functions (delivery search, logs, usage, etc.) are always available if authentication information is provided.
## Usage Examples
When the MCP server is set up for an AI agent, tools can be used directly in conversations.
Here are some examples:
- Check recent deliveries
```
Please show me a list of delivery results from last week.
```
- Check logs for a specific destination
```
Please display the email delivery logs for foo@example.com.
```
- Check usage
```
Please tell me the email usage for this month.
```
- Send a transactional email (requires `BLASTENGINE_ENABLE_SEND=true`)
```
Please create and send an email with the subject "Request for Payment" to yamada@example.com.
```
- Preview batch delivery (requires `BLASTENGINE_ENABLE_BULK=true`)
```
Please preview the content of batch delivery ID 123.
```
## Available Tools
Read-only tools require authentication information but have no side effects.
Sending tools are gated by the above feature flags.
| Tool | Type | Requirements |
| --- | --- |
| `blastengine_deliveries_list` | Read | Authentication information |
| `blastengine_delivery_get` | Read | Authentication information |
| `blastengine_mail_results_list` | Read | Authentication information |
| `blastengine_mail_log_get` | Read | Authentication information |
| `blastengine_usage_latest | Read | Authentication information `blastengine_usage_month_get` | Read | Authentication information `blastengine_bulk_import_status` | Read | |
| `blastengine_bulk_import_error_download` | Read (local file save) | Authentication information |
| `blastengine_bulk_preview` | Read (information presentation only) | `BLASTENGINE_ENABLE_BULK`blastengine_send_transaction (send) | `BLASTENGINE_ENABLE_SEND` |
| `blastengine_bulk_begin` | Write | `_ENABLE_BULK| `blastengine_b_recipients` | Write | `BLASTENGINE_ENABLE_BULK` |
| `blastulk_commit_scheduled` | Write (send) | `BLASTENGINE_ENABLE_BUL |
| `blastengine_bulk_commit_immediate` |send) | `BLASTENGINE_ENABLE_BULK` |
| `blastengine_bulk_import_recipients_csv` | WriteBLASTENGINE_ENABLE_BULK` + `BLASTENGINE_ENABLE_CSV_IMPORT` |
## Environment Variables
| Variable | Default Value | Purpose |
| --- | --- | --- |
| `BLASTENGINE_LOGIN_ID` | None | blastengine login ID used for Bearer token generation |
| `BLASTENGINE_API_KEY` | None | blastengine API for Bearer token generation |
| `BLASTENGINE_B_TOKEN` | None | Generated Bearer token. Takes precedence over login ID / API key when set |
| `BLASTENGINE_ENABLE_SEND` | `false` | Enable transactional sending |
| `BLASTENGINE_ENABLE_BULK` | `false` | Enable batch delivery tools |
| `BLASTENGINE_ENABLE_CSV_IMPORT` | `false` | Enable CSV destination import |
| `BLASTENGINE_BULK_MAX_RECIPIENTS` | `50` | Maximum number of recipients for `blastengine_bulk_update_recipients` |
| `BLASTENGINE_TIMEOUT_MS` | `30000` | HTTP timeout (milliseconds) |
| `BLASTENGINE_ACCEPT_LANGUAGE` | `ja-JP` | `Accept-Language` for API requests (`ja-JP` or `en-US`) |
| `BLASTENGINE_LOG_LEVEL` | `info` | stderr diagnostic log level (`silent` / `error` / `warn` / `info` / `debug`) |
| `BLASTENGINE_CLIENT_HEADERS` | `true` | Whether to send identification headers for usage tracking (mcp, version, tool name) |
※ Even if greater than 50 is specified for `BLASTENGINE_BULK_MAX_RECIPIENTS will be rejected by the blastengine API.
To register more than 50 destinations, use `blastengine_bulk_import_recipients_csv`.
## (HTTPS Inspection)
In an HTTPS inspection proxy environment, Node.js does not trust the corporate root CA by default,
and fail with `SELF_SIGNED_CERT_IN_CHAIN`.NODE_USE_SYSTEM_CA= to the server's `env`
to trust the OS's certificate store (equivalent to running `node --use-system-ca`):
```json
{
"mcpServers": {
"blastengine": {
": "node",
": ["/path/to/blastengine_mcp/dist/index.js"],
"env": {
"BLASTENGINE_LOGIN_ID": "...",
ASTENGINE_API_KEY": "...",
"NODE_USE_SYSTEM_CA": "1"
}
}
}
}
```
## Troubleshooting
| Error Code / Symptom | Cause and Solution |
| --- | --- |
| `missing_credentials` | Set `BLASTENGINE_LOGIN_ID` + `BLASTENGINE_API_KEY`BLASTENGINE_BEARER_TOKEN` |
| `send_disabled` / `bulk_disabled` / `csv_import_disabled` | The feature is disabled. Set the corresponding `BLASTENGINE_ENABLE_*` |
| `SELF_SIGNED_CERT_IN_CHAIN` | HTTPS inspection environment. Refer to "Corporate Network (HTTPS Inspection)" above |
| Client cannot connect | stdout is for MCP JSON-RPC only (diagnostics are on stderr). Check if `command` / `args` point to the built `dist/index.js` |
## Security
Authentication information remains within the local process and is not logged with email bodyrecipient list, CSV content, or prompts. Sending tools actually send emails, so use the minimum
privilege API key and run in a trusted environment. Do not include sensitive information like
authentication information or tokens in GitHub Issues.
## Information Sent
When calling the API, this server adds identification headers to track usage,
indicating that the request is via MCP. These headers do email body, recipient,
subject, authentication information,.
Headers always added:
- `User-Agent: blastengine-mcp/<version>` … Indicates that it's via MCP server version
When `BL_CLIENT_HEADERS=true`), the following headers are:
- `X-Client: mcp`
- `X-Bl-Client-Version: <version>`
- `X-Bl-MCP-Tool: <tool name>` … The tool (e.g.,engine_deliveries_list`)
- `X-Blastengine-MCP-Mode: <mode>` … The type of some operations like batch delivery
Setting `BLASTENGINE_CLIENT_HEADERS=false` can disable these `X-Blastengine-*` headers.
Note that `User-Agent` is always added regardless of this setting.
## Contributing
Please report requests, questions, and bug reports on GitHub Issues.
Pull requests from outside are not accepted.
See [CON.md](CONTRIBUTING.md) for details.
MIT. See](LICENSE).
