fmsg MCP server

fmsg-mcp

An MCP server that gives any AI agent its own fmsg address: send messages, follow threads, react, exchange attachments and wait for replies, through a deployed fmsg Web API. Connect through stdio in hosts such as Claude Code, Claude Desktop, Cursor and VS Code, or through HTTP using API-key headers or configured OAuth.

Use your choice of fmsg hosting provider, or self-host. No hosting provider or identity provider is built in.

authenticated by their own fmsg API key or OAuth connection.

• stdio for local hosts: one address per server process, configured by two environment variables.
• Streamable HTTP for shared or remote deployments: one endpoint serving many users, each

• The fmsg Web API client is exported for reuse: import { FmsgClient } from "@markmnl/fmsg-mcp/client".

1. Choose a connection

OAuth: connect and sign in

Get an OAuth-enabled MCP URL from your fmsg hosting provider, add it to your AI host, and sign in. You do not need an API key or a local installation for this connection. Your AI host must support the authorization server's client registration method; see OAuth onboarding. Operators can enable this with HTTP OAuth.

API key: use locally or over HTTP

You send as an fmsg address, authenticated by an API key (fmsgk_…) issued by your fmsg host:

API URL and API key for the address your agent will use.

• Using a hosting provider? Create an account with an fmsg hosting provider and obtain an

a key with fmsg-webapi api-key create.

• Self-hosting? Run the stack with fmsg-docker and issue

Use the API URL and key for local installation below, or use your provider's API-key MCP endpoint with an Authorization: Bearer fmsgk_... header. The endpoint must use the fmsg Web API that accepts your key.

MCP Registry

Find io.github.markmnl/fmsg-mcp in the official MCP Registry. The listing offers local npm installation and configurable remote connections for OAuth or API keys. For a remote connection, supply the MCP endpoint from your fmsg hosting provider or your own deployment; the registry input takes its hostname and path without the https:// prefix, such as mcp.example.com/mcp. OAuth sign-in is discovered from that endpoint; the API-key option additionally asks for your key. If your AI host cannot configure registry URL templates, add the full MCP URL directly instead.

2. Install

Requires Node.js 22 or later.

Claude Code

claude mcp add fmsg --scope user \
  --env FMSG_API_URL=https://api.example.com \
  --env FMSG_API_KEY=fmsgk_... \
  -- npx -y @markmnl/fmsg-mcp

Then in any session: "Send @bob@example.com a note about the release", "What's in my fmsg inbox?", "Wait for Bob's reply and answer it". /fmsg:chat and /fmsg:reply are available as prompts.

Claude Desktop, Cursor, VS Code and other stdio hosts

Add a server entry with the same command; only the config file differs:

{
  "mcpServers": {
    "fmsg": {
      "command": "npx",
      "args": ["-y", "@markmnl/fmsg-mcp"],
      "env": { "FMSG_API_URL": "https://api.example.com", "FMSG_API_KEY": "fmsgk_..." }
    }
  }
}

(Claude Desktop: claudedesktopconfig.json; Cursor: .cursor/mcp.json; VS Code: .vscode/mcp.json under "servers" with "type": "stdio".)

Remote (Streamable HTTP) mode

Shortened. The full README is on GitHub.