Metadata-Version: 2.5
Name: dms-mcp
Version: 0.1.0
Summary: MCP server for administering docker-mailserver via its setup CLI
Author: obaaio
License-Expression: MIT
License-File: LICENSE
Keywords: docker-mailserver,dovecot,email,mcp,model-context-protocol,postfix
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Email :: Mail Transport Agents
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Requires-Dist: mcp<3,>=2.3
Description-Content-Type: text/markdown

# dms-mcp

An MCP server for administering [docker-mailserver](https://github.com/docker-mailserver/docker-mailserver).
Each tool wraps the container's `setup` script (`docker exec -i <container> setup ...`), locally or on a remote host over SSH.

## Tools

| Area | Tools |
|---|---|
| Accounts | `list_accounts`, `add_account`, `update_password`, `delete_account`, `list_restrictions`, `restrict_account` |
| Aliases | `list_aliases`, `add_alias` (supports `@domain` catch-all), `delete_alias` |
| Quotas | `set_quota`, `delete_quota` |
| DKIM | `generate_dkim`, `show_dkim_record` |
| Fail2ban | `fail2ban_status`, `fail2ban_ban`, `fail2ban_unban` |
| Ops | `mail_log` (tail + filter), `mail_queue`, `flush_queue`, `server_status` |

- Passwords go over stdin and never appear in process arguments. If you omit the password, the tool generates a 24-character one and returns it.
- `delete_account` keeps stored mail unless `delete_mail=true`.
- Every input is validated (addresses, domains, IPs, quotas), and in SSH mode every argument is shell-quoted.
- Tools carry read-only/destructive hints, so MCP clients can ask for confirmation before destructive actions.

## Install

No clone needed. Run it straight from PyPI with [uv](https://docs.astral.sh/uv/):

```bash
uvx dms-mcp --version
```

or install it as a command with pipx or pip:

```bash
pipx install dms-mcp     # or: pip install dms-mcp
```

## Configure

| Env var | Default | Purpose |
|---|---|---|
| `DMS_CONTAINER` | `mailserver` | Container name |
| `DMS_SSH_HOST` | (unset) | e.g. `admin@mail.example.com`, which runs docker on that host over SSH (needs key auth) |
| `DMS_DOCKER_BIN` | `docker` | Docker binary on the target host |
| `DMS_TIMEOUT` | `60` | Per-command timeout in seconds |

Instead of `DMS_SSH_HOST`, you can also set `DOCKER_HOST=ssh://admin@mail.example.com` or `DOCKER_CONTEXT`; the docker CLI handles both natively.

### Claude Code

```bash
claude mcp add dms -s user \
  -e DMS_SSH_HOST=admin@mail.example.com -e DMS_CONTAINER=mailserver \
  -- uvx dms-mcp
```

### Claude Desktop / Cursor / other clients (`mcpServers` JSON)

```json
{
  "mcpServers": {
    "dms": {
      "command": "uvx",
      "args": ["dms-mcp"],
      "env": { "DMS_SSH_HOST": "admin@mail.example.com", "DMS_CONTAINER": "mailserver" }
    }
  }
}
```

If you installed with pipx/pip, use `"command": "dms-mcp"` and drop `args`.

## Security

Running this server is the same as having shell access to the mail container, and docker access usually means root on that host. Use a dedicated SSH key, and consider restricting it with a `command=` wrapper in `authorized_keys` that only allows `docker exec -i mailserver ...`.

## Development

```bash
python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/python tests/test_server.py   # uses a stub docker binary, no server needed
```

## Releasing

CI (`.gitea/workflows/ci.yaml`) runs the tests on every push and PR. To publish to PyPI:

1. Bump `version` in `pyproject.toml` and commit.
2. Tag and push: `git tag v0.1.0 && git push origin v0.1.0`

The publish job checks that the tag matches the version in `pyproject.toml`, then uploads using the `PYPI_API_TOKEN` org secret.
