Claws Mail MCP Plugin (io.github.it-atelier-gn/claws-mail-mcp-plugin)

The Claws Mail MCP plugin exposes a running Claws Mail mail client over a local MCP endpoint secured with a bearer token. It provides integration for tooling that can connect to the endpoint and interact with the mail client’s available capabilities.

🛠️ Key Features

Local MCP endpoint
Bearer-token access
Exposes a running Claws Mail mail client

🚀 Use Cases

Access and automation workflows targeting a Claws Mail instance
Developer-driven integration with a locally running mail client via MCP

⚡ Developer Benefits

Standardized MCP interface for consuming mail client functionality
Token-based local access for controlling connectivity

claws-mail-mcp-plugin

Native Claws Mail plugin that exposes the running mail client as an MCP server.

It runs inside Claws Mail and serves a local, loopback-only HTTP endpoint (JSON-RPC over MCP, bearer-token protected). Any MCP-capable AI tool can then read folders and messages, search, compose, reply, forward, manage folders and flags, and send or receive mail through your already-configured accounts. Endpoint, port, token and read-only mode are set in mcp_pluginrc inside the Claws Mail config directory; the plugin writes a ready-to-paste client config to mcp_client.json in the same place on every start.

Installing the plugin

Prebuilt binaries are attached to each release, one per OS and supported Claws Mail version (e.g. mcp_plugin-linux-claws4.3.1.so, mcp_plugin-windows-claws4.3.0.dll). Pick the file matching your Claws Mail version and OS, then:

Copy it into your Claws Mail plugin directory (pkg-config --variable=plugindir claws-mail, typically ~/.claws-mail/plugins or %APPDATA%\Claws-mail\plugins on Windows).
Restart Claws Mail.
Enable it under Configuration > Plugins if it is not loaded automatically.

To build from source instead, see Building.

Connecting an AI tool

Once loaded, the plugin writes the real endpoint URL and bearer token to mcp_client.json in the Claws Mail config directory. Use those two values with whichever method below matches your tool. The server is loopback-only (127.0.0.1), so it is reachable only from AI tools running on the same machine as Claws Mail.

Claude Code

code

claude mcp add --transport http claws-mail http://127.0.0.1:8765/mcp \
  --header "Authorization: Bearer <TOKEN>"

Claude Desktop

Settings > Developer > Edit Config, then merge in packaging/claude/mcp.json (fill in <TOKEN>). Do not use the "Add custom connector" UI for this server: that flow connects from Anthropic's servers, not from your machine, so it cannot reach a loopback address.

VS Code / GitHub Copilot Chat

code

code --add-mcp "{\"name\":\"claws-mail\",\"type\":\"http\",\"url\":\"http://127.0.0.1:8765/mcp\",\"headers\":{\"Authorization\":\"Bearer <TOKEN>\"}}"

Or copy packaging/vscode/mcp.json to .vscode/mcp.json; it prompts for the token instead of storing it in the file.

Codex CLI

code

export CLAWS_MCP_TOKEN=<TOKEN>
codex mcp add claws-mail --url http://127.0.0.1:8765/mcp --bearer-token-env-var CLAWS_MCP_TOKEN

This matches packaging/codex/config.toml, which Codex reads from ~/.codex/config.toml.

MCP registry

packaging/registry/server.json is published to the MCP registry as io.github.it-atelier-gn/claws-mail-mcp-plugin on every tagged release, via .github/workflows/ci.yml's publish-registry job (GitHub OIDC auth, no stored credentials). The registry rejects loopback URLs as remotes, so this is a discovery-only listing without connection details; it links back to this README for installation and the per-tool commands above.

Building

Requires Meson, Ninja, a C compiler, and the Claws Mail development files (GTK3, GLib, GnuTLS, libgcrypt, enchant).

Linux

Install dependencies (Debian/Ubuntu example):

code

sudo apt-get install build-essential meson ninja-build pkg-config \
  libgtk-3-dev libglib2.0-dev libgnutls28-dev libgcrypt20-dev libenchant-2-dev

If a claws-mail pkg-config file is not already on your system, build one with:

code

PREFIX="$PWD/.claws-sdk" ci/build-claws-sdk.sh
export PKG_CONFIG_PATH="$PWD/.claws-sdk/lib/pkgconfig"

Then configure and build:

code

meson setup build
meson compile -C build
meson test -C build

The plugin is built at build/mcp_plugin.so.

Windows (MSYS2)

Install the MINGW64 toolchain and dependencies:

code

pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-meson mingw-w64-x86_64-ninja \
  mingw-w64-x86_64-pkgconf mingw-w64-x86_64-gtk3 mingw-w64-x86_64-glib2 \
  mingw-w64-x86_64-gnutls mingw-w64-x86_64-libgcrypt mingw-w64-x86_64-enchant

Build the Claws Mail SDK and set PKG_CONFIG_PATH as above, then run the same meson setup / meson compile / meson test commands. The plugin is built at build/mcp_plugin.dll.

Plugin version

The version compiled into the binary (returned by plugin_version and the status tool) comes from -Dplugin_version, e.g.:

code

meson setup build -Dplugin_version=1.2.3

CI sets this from the pushed git tag on release builds. Without it, the build falls back to git describe, then to 0.0.0-dev.

Installing

code

meson install -C build

This installs the plugin into the Claws Mail plugin directory reported by pkg-config --variable=plugindir claws-mail.

Supported Claws Mail versions

CI builds and tests the plugin against every version listed in ci/claws-versions.json, on both Linux and Windows. Each combination gets its own release artifact.

A scheduled workflow (.github/workflows/check-claws-version.yml) checks the Claws Mail release feed weekly. When it finds a version not yet in ci/claws-versions.json, it trial-builds the plugin against it on both OSes. If that succeeds, it opens a pull request adding the version to the supported list; if it fails, it opens an issue instead.

License

GPL-3.0-or-later, see LICENSE.