fmsg

fmsg-mcp

あらゆる AI エージェントに独自の fmsg アドレスを提供する MCP サーバーです。デプロイ済みの fmsg Web API を通じて、メッセージの送信、スレッドのフォロー、リアクション、添付ファイルの交換、返信の待機ができます。Claude Code、Claude Desktop、Cursor、VS Code などのホストとは stdio で、または API キーヘッダーや設定済み OAuth を使って HTTP で接続できます。

お好みの fmsg ホスティングプロバイダーを利用するか、セルフホストしてください。ホスティングプロバイダーや ID プロバイダーは組み込まれていません。

• stdio はローカルホスト向けです。サーバープロセスごとに 1 つのアドレスを使用し、2 つの環境変数で設定します。
• Streamable HTTP は共有またはリモートのデプロイ向けです。1 つのエンドポイントで多数のユーザーに対応し、各ユーザーはそれぞれの fmsg API キーまたは OAuth 接続で認証します。
• fmsg Web API クライアントは再利用できるようにエクスポートされています：import { FmsgClient } from "@markmnl/fmsg-mcp/client"。

1. 接続方法を選択

OAuth：接続してサインイン

fmsg ホスティングプロバイダーから OAuth 対応の MCP URL を取得して AI ホストに追加し、サインインします。この接続では、API キーもローカルインストールも必要ありません。AI ホストは認可サーバーのクライアント登録方式に対応している必要があります。詳しくはOAuth のオンボーディングをご覧ください。運用者はHTTP OAuthを有効にできます。

API キー：ローカルまたは HTTP で使用

fmsg アドレスとして送信し、fmsg ホストが発行した API キー（fmsgk_…）で認証します。

• ホスティングプロバイダーを利用する場合： fmsg ホスティングプロバイダーでアカウントを作成し、エージェントが使用するアドレスの API URL と API キーを取得します。
• セルフホストする場合： fmsg-docker でスタックを実行し、fmsg-webapi api-key create でキーを発行します。

以下のローカルインストールでは API URL とキーを使用するか、Authorization: Bearer fmsgk_... ヘッダーを使ってプロバイダーの API キー対応 MCP エンドポイントを使用します。エンドポイントは、キーを受け付ける fmsg Web API を使用する必要があります。

エージェントのキーは通常、@[email protected] が所有する @[email protected] などのサブアドレス用です。所有者はクライアントでサブアドレスに切り替えられますが、自分が参加者であるスレッドのみフォローおよび返信できます。そのため、include_owner が false でない限り、send_message、reply、create_draft は所有者を受信者に追加します。whoami は所有者を報告します。

MCP Registry

公式 MCP Registryで io.github.markmnl/fmsg-mcp を探してください。掲載ページでは、ローカルの npm インストールと、OAuth または API キーを使う設定可能なリモート接続を利用できます。リモート接続の場合は、fmsg ホスティングプロバイダーまたは独自のデプロイから MCP エンドポイントを指定してください。レジストリの入力には https:// 接頭辞を付けず、ホスト名とパスを指定します。例：mcp.example.com/mcp。OAuth サインインはそのエンドポイントから検出されます。API キーのオプションでは、キーの入力も求められます。AI ホストでレジストリ URL テンプレートを設定できない場合は、MCP URL 全体を直接追加してください。

2. インストール

Node.js 22 以降が必要です。

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

その後、任意のセッションで「@[email protected] にリリースについてのメモを送って」「fmsg の受信トレイには何がある？」「Bob の返信を待って、返事をして」と頼めます。/fmsg:chat、/fmsg:reply、/fmsg:send_file をプロンプトとして利用できます。

Claude Desktop、Cursor、VS Code、その他の stdio ホスト

同じコマンドでサーバーエントリを追加します。異なるのは設定ファイルだけです。

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

（Claude Desktop：claude_desktop_config.json、Cursor：.cursor/mcp.json、VS Code："servers" 内の .vscode/mcp.json。その場合は "type": "stdio" を指定します。）

リモート（Streamable HTTP）モード

複数のユーザー向けにサーバーを1つ実行します。各クライアントは自身の fmsg API キーをベアラートークンとして送信します。サーバーはそのキーを fmsg ホストで交換し、そのアドレスとして動作します。FMSG_API_KEY を設定してはいけません。

FMSG_API_URL=https://api.example.com FMSG_MCP_ALLOWED_HOSTS=mcp.example.com \
  npx -y @markmnl/fmsg-mcp --http 0.0.0.0:8765
# or
docker build -t fmsg-mcp .
docker run -e FMSG_API_URL=https://api.example.com \
  -e FMSG_MCP_ALLOWED_HOSTS=mcp.example.com -p 8765:8765 fmsg-mcp

MCP エンドポイントは /mcp で、/healthz は稼働状態を報告します。明示的に設定された Authorization: Bearer fmsgk_... ヘッダーに対応するクライアントを使用してください。各呼び出し元は自身のキーを指定します。共有ヘッダーを使うと、fmsg の同一ユーザーとして扱われます。ユーザー API キーなしでブラウザーサインインを利用するには、HTTP OAuth を設定します。運用者は発行者、リソース URI、交換クライアントを指定します。ユーザーは、その発行者のクライアント登録方式に対応するホストに、公開 MCP URL を追加します。FMSG_MCP_AUTH_MODE=oauth+api-key を設定すると、同じ URL で OAuth と API キーの両方の呼び出しを受け付けます。

HTTP 経由の Claude Code の場合：

claude mcp add --transport http fmsg --scope user https://mcp.example.com/mcp \
  --header "Authorization: Bearer fmsgk_..."

TLS を終端するリバースプロキシの背後にデプロイし、ループバック以外のアドレスにバインドする場合は、FMSG_MCP_ALLOWED_HOSTS に公開ホスト名を設定してください。設定されていない場合、起動に失敗します。別のオリジンから接続するブラウザクライアントには、https://app.example.com のような正確なオリジンを含む FMSG_MCP_ALLOWED_ORIGINS も必要です。ループバックへのバインドでは、MCP Inspector の http://localhost:6274 も含め、任意のポートのループバックブラウザーオリジンがデフォルトで許可されます。オリジンリストを明示的に設定すると、このループバックのデフォルトは置き換えられます。許可されたプリフライトには認証情報は不要ですが、実際の MCP リクエストには常に認証が必要です。wait_for_message はリクエストを最大 FMSG_MCP_WAIT_MAX_SECONDS（230 秒）まで開いたままにするため、プロキシのアイドルタイムアウトは少なくとも 240 秒に設定してください。SIGTERM を受信すると、サーバーは開いている待機を interrupted 結果で終了し、クライアントがそこから再開できるようにします。ほかのリクエストには 5 秒間の完了猶予を与えてから終了するため、サービスマネージャーの停止タイムアウトを十分に下回ります。Caddy を使ったループバックデプロイについては、TLS リバースプロキシの例を参照してください。

ツール

ツール	機能
whoami	このサーバーが動作するアドレス、サブアドレスの場合はその owner、公開 API URL（判明している場合）、トランスポート（stdio または http。後者は Streamable HTTP です）、短縮名のデフォルト
resolve_address	短縮名を @user@domain に変換します（ディレクトリ、次にデフォルトドメインを参照）
list_messages	受信トレイを新しい順に表示します。プレビュー、添付ファイルの種類、size（compressed は本文が deflate 圧縮されて送信されたことを示します）が含まれます。リアクションは非表示で、include_reactions が指定されない限り未読数には含まれません
list_sent	送信済みメッセージと、受信者ごとの配信状態
get_message	ヘッダー、全文の本文、添付ファイル、リアクション、および返信の場合はスレッドのルートの thread_topic を含む単一のメッセージ
get_thread	スレッドのルートからメッセージまでの系譜（scope: "lineage"。スレッド内の他の返信は含まれません）。閲覧できないメッセージは抜けとして示され、メッセージごとのフラグと追加された受信者、ルートの thread_topic、および終端メッセージや返信不可メッセージへの返信を決して提案しない next ステップが含まれます
send_message	新しいスレッドを開始します。即時に送信されます（fmsg メッセージは変更できません）
reply	スレッドに返信します。デフォルトでは全員に返信し、終端メッセージや返信不可の親メッセージへの返信は拒否します
create_draft	未送信のメッセージまたは返信（reply_to）を作成します。他の fmsg クライアントからも確認できます。公開 MCP URL を使用する HTTP では、大きな添付ファイル用の認証付きアップロード URL を返します
send_draft	下書きを添付ファイルとともに送信します
delete_draft	未送信の下書きを破棄します
add_recipients	送信済みメッセージに recipients を追加します（add_to は非推奨のエイリアスです）
react	自分の絵文字リアクションを設定または解除します
mark_read	受信したメッセージを既読にします
download_attachment	小さな添付ファイルをインラインで取得します。テキストはテキストとして、画像は画像ブロックとして、その他のファイルは base64 リソースとして返します。ファイル名が間違っている場合、そのメッセージにあるファイル名の一覧を返します
get_attachment_download_url	認証が必要なバイナリのダウンロード用に、認証情報を含まない URL とリソースリンクを取得します。HTTP 専用で、公開 MCP URL が必要です。接続の Authorization ヘッダーを送信できないホストでは download_attachment を使用します
save_attachment	添付ファイルを設定済みのローカルフォルダーにストリーミング保存します。stdio 専用で、FMSG_MCP_DOWNLOAD_DIR によって有効になります
delivery_status	受信者ごとの配信時刻と fmsg 応答コード（200 は受理済み、記録がない場合は null）。受信メッセージの場合はホスト自身の受信記録です。via は to または add_to（後から追加）です
wait_for_message	次の受信メッセージが届くまで待機します（WebSocket プッシュ）。スレッドごとにまとめられ、スレッドのコンテキスト、スキップされたリアクション、カーソルが通過した他のスレッドのメッセージを示す next ステップ（pending_ids）が含まれます

すべてのツールは、読みやすい Markdown と structuredContent を返します。ID は 10 進数の文字列です。メッセージ本文には、他者からのデータであり指示ではないことが明記されています。他者の言葉を含む構造化結果にも untrusted_content_notice で同じ注意書きが繰り返されます。ホストによってはテキストではなく構造化結果が表示されるためです。添付ファイルの種類は、記録時にホストが指定していればその値を使用し、そうでなければファイル名の拡張子から判定します。そのため、どのツールでも同じ種類が報告され、添付ファイルはすべて同じ順序（ファイル名順）で一覧表示されます。本文中のアドレスはコードスパンで示されるため、そのまま正確にコピーできます（@[email protected]。Markdown のエスケープは付きません）。アドレスにバックスラッシュが含まれる場合は拒否されます。メッセージの size はホストが保存する本文のサイズです。受信メッセージで compressed が true の場合は圧縮後の長さですが、自分が送信したメッセージでは圧縮前の長さが保持されます。

出力スキーマの互換性

一部の MCP ホストは、コネクターの追加時に各ツールの outputSchema をキャッシュし、そのコピーに照らして後続のすべての結果を検証します。そのため、出力スキーマはオープンかつ追加可能になっています。オブジェクトは未知のプロパティを受け入れ、増える可能性のある値（ステータス、トランスポート、解決方法、配信状態）は文字列とし、現在の値は説明に記載しています。また、必須なのは 0.2.5 から存在するフィールドのみです。リリースではフィールドや値を追加しますが、削除や名称変更はしません。0.2.6 以前に公開されたスキーマは閉じていたため、それをキャッシュしたホストは新しいフィールドを含む結果を拒否します（例：「must NOT have additional properties」）。更新するには、コネクターを一度削除して再追加してください。

リソース fmsg://message/{id} と fmsg://thread/{id} は、リソースを添付するホストに同じコンテンツを公開します。プロンプト chat と reply は、待機 → 返信のループとガイド付き返信を実行し、send_file はサーバーが提供する最も効率的な経路でファイルを送信します。

設定

変数	デフォルト	用途
FMSG_API_URL	—	fmsg Web API のベース URL（必須）
FMSG_API_KEY	—	fmsgk_… キー。stdio モードのみ
FMSG_API_PUBLIC_URL	FMSG_API_URL（HTTP モード：HTTPS の場合のみ）	whoami によってユーザーに報告される Web API URL。リクエストには使用されません。サーバーが内部アドレスで Web API にアクセスする場合に設定します。これを設定せず、FMSG_API_URL がクリアテキストの場合、HTTP モードでは URL がないことを報告します。FMSG_API_URL と同様に検証されます
FMSG_MCP_AUTH_MODE	api-key	HTTP 認証：api-key、oauth、または 1 つのエンドポイントで両方を受け入れる oauth+api-key。OAuth の設定および複合モードを参照してください
FMSG_MCP_PUBLIC_URL	OAuth リソース URL。それ以外は未設定	/mcp を含む公開 MCP エンドポイント。HTTP ダウンロードリンクツールとドラフトのアップロード URL を有効にします。ループバック以外では HTTPS が必要です。OAuth が有効な場合は FMSG_MCP_OAUTH_RESOURCE_URL と一致する必要があります
FMSG_ALLOW_INSECURE_HTTP	無効	信頼できる開発用／プライベートネットワークでクリアテキストの API アクセスを許可する場合のみ 1 に設定します。ループバックの HTTP はデフォルトで許可されます
FMSG_DEFAULT_DOMAIN	—	短い名前を解決できるようにします：bob → @bob@<domain>。caller は、各リクエストでサーバーが使用するアドレスのドメイン上で名前を解決するため、@[email protected] の場合は @[email protected] になります。ディレクトリのエントリーがある場合は、引き続きそちらが優先されます
FMSG_DIRECTORY	—	短い名前を完全なアドレスに対応付ける JSON ファイル
FMSG_MCP_DOWNLOAD_DIR	—	stdio で save_attachment を有効にします。メッセージ ID とファイル名を基に新しいファイル名を付けるフォルダー
FMSG_MCP_UPLOAD_DIR	—	stdio で添付ファイルの path 引数を許可します。このフォルダー内（またはその配下）のファイルは、モデルが書き出すのではなくサーバーが読み込みます
FMSG_MCP_WAIT_MAX_SECONDS	230	1 回の wait_for_message 呼び出しの上限
FMSG_MCP_HOST / FMSG_MCP_PORT	127.0.0.1 / 8765	HTTP のバインドアドレス（または --http host:port）
FMSG_MCP_ALLOWED_HOSTS	ループバック名	Host ヘッダーの許可リスト（カンマ区切り）。ループバック以外にバインドする場合は必須
FMSG_MCP_ALLOWED_ORIGINS	同一オリジン。ループバックにバインドする場合はループバックのオリジン	スキームとポートを含むブラウザーオリジン（カンマ区切り）。明示的なリストを指定すると、ループバックのデフォルト設定は置き換えられます。ホスト名だけの値は拒否されます
FMSG_MCP_KEY_CACHE_MAX / FMSG_MCP_KEY_CACHE_TTL_SECONDS	500 / 1800	HTTP クライアントキャッシュの上限。TTL は API キーの呼び出し元にのみ適用されます

API キーは短期間有効なアクセストークンと交換され、サーバーが自動的に更新します。 API URL に認証情報、クエリー文字列、フラグメントを含めてはいけません。認証済みリクエストはリダイレクトを追従しません。最終的な API URL を直接設定してください。 添付ファイルをディスクに直接保存するには、stdio サーバーの環境変数に FMSG_MCP_DOWNLOAD_DIR を追加します。たとえば、/home/you/Downloads/fmsg を指定します。任意の save_attachment ツールは、ファイルのバイト列をモデルコンテキストに送信せずに、このフォルダーへファイルをストリーミングします。メッセージ ID と添付ファイル名のみを受け取り、123-report.pdf などの新しいファイルを作成します。繰り返し保存する場合は、既存のファイルに触れずに 123-report-1.pdf、123-report-2.pdf などの名前が使われます。特殊なファイル名は、移植可能な名前に変換されます。返された saved_to パスを使用してください。ストリーミングダウンロードは、進行中であれば 60 秒を超えることがあります。転送の停滞は、60 秒のアイドルタイムアウトによって検出されます。

インラインダウンロードの上限は、ファイルの内容をモデルが扱いやすいよう、デフォルトで 256 KiB です。サイズの大きなローカルファイルには save_attachment（stdio）、リモートファイルには get_attachment_download_url（HTTP）を使用するか、AI ホストがより大きなインラインコンテンツを扱える場合は、max_inline_bytes を明示的に引き上げてください。ツールの説明には、実行中のサーバーが登録したツールのみが記載されます。

リモートファイルをダウンロードするには、メッセージ ID とファイル名を指定して get_attachment_download_url を呼び出します。このツールはメタデータと HTTPS の resource_link を返します。AI ホストは、既存の MCP 接続の Authorization ヘッダーを使って元のバイト列をダウンロードします。API キーを使用する運用者は、FMSG_MCP_PUBLIC_URL=https://mcp.example.com/mcp を指定してこのツールを有効にします。OAuth を使用するデプロイでは、設定済みのリソース URL が自動的に再利用されます。バイナリ添付ファイルのダウンロードを参照してください。リンクに認証情報は含まれておらず、リンクだけでアクセスが許可されることもありません。ホストは認証付き HTTP ダウンロードに対応している必要があります。ヘッダーなしで通常のブラウザーからリンクをクリックすると、401 が返されます。そのホスト機能を利用できない場合は、インラインダウンロードを使用してください。ダウンロードはインラインサイズ上限の対象外でストリーミングされ、元の Content-Type とダウンロードファイル名が使用されます。MCP サーバーにはファイルは保存されません。

添付ファイルの送信

send_message、reply、create_draft では、各添付ファイルに次のいずれか1つを指定します。

• data_base64：モデルが生成するBase64データです。小さなファイルに適しています。標準またはURLセーフの文字セットを使用できますが、1つの値に両方を混在させることはできません。デコードは厳密に行われます。その他の文字、不正な長さやパディング、余分な末尾文字がある場合は、破損したファイルとして送信せず、添付ファイル名とともに拒否されます。
• data_text：テキストをUTF-8バイトとして送信します。Base64によるオーバーヘッドはありません。
• path（stdioでFMSG_MCP_UPLOAD_DIRを指定）：そのフォルダー内のファイルをサーバーがストリーミングします。パスはフォルダーを基準とし、フォルダー外につながるパスやシンボリックリンクは拒否されます。

添付ファイルにsha256（16進数）を指定すると、サーバーはバイト列を照合します。一致しない場合は、送信前に拒否されます。HTTP経由で大きなファイルを送信する場合は、create_draftを呼び出し、返されたアップロードURLに接続のAuthorizationヘッダーを付けてファイルをPUTし（任意でgzip圧縮し、x-content-sha256を指定できます）、その後send_draftを呼び出してください。添付ファイルのアップロードを参照してください。ファイルはそのまま送信してください。fmsgは送信時にメッセージ本文と添付ファイルをそれぞれ圧縮します。

モデルはサーバーの指示とツールの説明からルートを学習します。そこに記載されるのは、稼働中のサーバーが提供するルートだけです。より適切なルートがあるにもかかわらず、モデルが大きなファイルをBase64で書き出した場合、結果にそのルートを示すhintが含まれます。send_fileプロンプトでは、最適なルートを順を追って説明します。アップロードURLの利用には、MCP接続の認証情報を独自のHTTPリクエストに付けて送信できるホストが必要です。たとえば、スクリプト、SDKクライアント、fmsg APIキーを付与されたコーディングエージェントが該当します。通常、チャットホストではそれができないため、そうしたホストでは引き続きdata_textとdata_base64を使用します。

Web APIでは、添付ファイルはすでに生のバイト列として転送されます。Base64は、MCPバイナリーリソースの要件に従い、MCPのJSON結果にバイナリーコンテンツを埋め込む場合にのみ使用されます。save_attachmentと認証済みHTTPダウンロードでは、このエンコードを避け、ファイルのバイト列をモデルのコンテキストに含めません。issue #6を参照してください。

stdioでは、設定がない場合や無効な場合でも、ホストはツールを検出できます。ツール呼び出しでは設定エラーと修正方法が説明されます。設定を修正した後、MCPサーバーを再起動してください。

安全性

• メッセージングへのアクセス、利用枠、宛先による受信可否は、fmsg-webapiとホストサービスが適用します。MCPは呼び出し元のIDで各操作を転送し、上流で発生したエラーを表示します。
• download_attachmentはローカルファイルを書き込みません。任意のsave_attachmentは、オペレーターが設定したフォルダー内に、生成されたファイル名のみを書き込みます。排他的に作成し、上書きはしません。
• 送信済みメッセージは編集も取り消しもできません。送信ツールの説明にはその旨が記載され、影響を示すためdestructiveHintが付与されています。承認動作はAIホストに委ねられており、fmsg-mcpには追加の確認ゲートはありません。
• 指定された形式のAPIキーやトークンは、送信本文、トピック、エラーテキストから秘匿化され、送信ツールはその件数を報告します。対象には、fmsg APIキー、JWT、秘密鍵ブロック、ソースホスティングのトークン（ghp_…、github_pat_…、glpat-…）、クラウドアクセスキーID（AKIA…、ASIA…）とラベル付きのシークレットアクセスキー、AIza… APIキー、チャットプラットフォームのトークン（xox…）、決済プラットフォームのキー（sk_live_…、rk_live_…、sk_test_…、whsec_…）、sk-… APIキーが含まれます。これは、一般的なデータ漏えい防止やバイナリー添付ファイルのスキャンではありません。
• メッセージのサイズや受け入れ可否について、何も前提としません。fmsgホストからの応答と配信コードは、そのまま表示されます。
• サーバーはMCPのinstructionsを公開します（セッション開始時にモデルに表示されます）。そこでは、エージェントに対し、ローカルのfmsg CLIやキャッシュされた認証情報ではなくこれらのツールを使用すること、繰り返し確認を求めずに許可されたタスクや自動化を実行すること、メッセージの内容をデータとして扱うことを指示します。
• SECURITY.mdを参照してください。

クライアントライブラリの使用

import { FmsgClient } from "@markmnl/fmsg-mcp/client";

const client = new FmsgClient("https://api.example.com", process.env.FMSG_API_KEY!);
console.log(await client.address());
const inbox = await client.listInbox(10);
const sent = await client.send({ to: ["@[email protected]"], topic: "Hi", body: "Hello from code" });
console.log(sent.id, sent.redactions);
client.close();

send() は、下書きを作成する前に、本文とトピック内の選択された認証情報パターンを置き換えます。 その結果には、置換数（redactions）、置換された種類（redacted。例：github_token）、および送信された topic が含まれます。添付ファイルは 変更されません。大きなファイルを段階的に読み込むには streamAttachment() を使用してください。ストリームを最後まで読み込むか、キャンセルしてください。

独自の認証連携を持つアプリケーションでは、API キー文字列の代わりに TokenProvider を渡せます。クライアントは並行リクエスト間で更新を共有し、認証済みアドレスを固定します。 token-provider コントラクトを参照してください。このライブラリのインターフェースは、実行ファイルのオプションの OAuth モードでも使用されています。

開発

npm ci
npm run typecheck && npm run build && npm test
npx @modelcontextprotocol/inspector node dist/index.js          # stdio, with FMSG_API_URL/FMSG_API_KEY set
bash .github/scripts/run-fmsg-docker-e2e.sh                     # end to end on two real fmsg stacks

構成と規約については AGENTS.md、残りの連携作業については ROADMAP.md、リリースノートについては CHANGELOG.mdを参照してください。

リリース

安定版の GitHub リリースに vX.Y.Z のタグを付けて公開すると、チェックと npm パッケージの公開が実行されます。その後、同じバージョンで MCP Registry を更新してください。どちらも OIDC 認証を使用するため、専用のレジストリシークレットは不要です。ドラフトとプレリリースでは公開されません。レジストリへの公開は別のジョブとして実行されるため、npm の公開後に失敗した場合は、リリースワークフローで 失敗したジョブを再実行してください。

MIT ライセンス