mail

This MCP server implements a mail-sending capability exposed as an MCP tool. Built with Spring AI, it uses the MCP framework to surface business logic (in this case, sending emails) as a tool that the large model can call. The server demonstrates how to look up recipient addresses by name and dispatch emails via JavaMailSender, all wired through the MCP Tool annotation so the model can invoke it with a structured input. To use it, deploy the server (for example via Docker as shown in the installation guide), then interact with the MCP surface to call the sendMail tool with a proper input object. The tooling is designed to be discoverable through the MCP server’s tool list, and the tool description clarifies the required inputs and their meanings so the model can compose calls correctly.

Prerequisites:

• JDK 17 or higher
• Maven or Gradle for building (examples use Maven)
• Docker installed if you plan to run via Docker
• SMTP credentials for the mail server (host, port, username, password)

Option A: Run directly with Java (local development)

1. Clone the repository
2. Build the project

mvn clean package -DskipTests

3. Run the produced jar (example path will depend on your project structure)

java -jar target/mail-mcp-server-0.0.1-SNAPSHOT.jar

4. Verify the server starts and exposes the MCP endpoints (SSE /mcp/message by default as configured). Ensure SMTP settings are provided via application.yml or environment variables.

Option B: Run with Docker (recommended for isolation)

1. Ensure SMTP environment variables are set, or provide a docker-compose with them.
2. Start the container

docker run -d --name mail-mcp-server \
  -e SPRING_MAIL_HOST=smtp.example.com \
  -e SPRING_MAIL_PORT=587 \
  -e SPRING_MAIL_USERNAME=you@example.com \
  -e SPRING_MAIL_PASSWORD=yourpassword \
  -p 8080:8080 \
  rtexception/mail-mcp-server:latest

3. The MCP server should be accessible on port 8080 of the host. Check logs for initialization success.

Option C: Use a cloud or internal registry image

• Push the built image to your registry and run using docker run with updated image name.

Prerequisites summary:

• JDK 17+
• Maven or Gradle
• If using Docker, Docker daemon running
• SMTP service accessible from the server

Notes and tips:

• The MailServiceImpl demonstrates an MCP Tool named sendMail. When you implement additional mail-related capabilities, annotate methods with @Tool and describe parameters with @ToolParam to expose them as MCP tools.
• Ensure your SMTP configuration is secure. Do not hard-code passwords in code; use environment variables or externalized configuration (e.g., application.yml, Kubernetes Secrets).
• The server configuration in application.yml includes several MCP-specific settings (sse-message-endpoint, sse-endpoint, and notification toggles). Adjust these if you need to customize how the MCP server communicates over SSE and how it notifies about tool changes.
• If you encounter issues with tool invocation, verify that the model’s prompt includes the correct tool name (sendMail) and provides all required fields as defined by the tool parameter descriptors.
• For local testing, you can mock the JavaMailSender bean or configure a local SMTP server (e.g., MailHog) to avoid sending real emails during development.