esa MCP server

esa MCP Server

日本語 | English

esa.io の公式 MCP(Model Context Protocol)サーバー(STDIO Transport 版)

概要

AI アシスタントと情報共有サービス esa をつなぐ MCP サーバーです。Model Context Protocol 経由で、AI アシスタントから esa の記事を読んだり、作成・更新・管理などができます。

使えるツール

チーム管理

• esagetteams - 所属している esa チームの一覧
• esagetteam_stats - チームの統計情報（メンバー数、記事数、コメント数など）
• esagetteam_tags - チーム内で使われているタグと使用回数
• esagetteam_members - チームメンバーとその役割・プロフィール

記事管理

• esasearchposts - 記事を検索
• esagetpost - 記事 ID から記事を取得（バックリンク総数 backlinkscount、本文の文字数・行数 bodymd_stats を含む）
• esagetpost_backlinks - 指定記事を参照している記事の一覧（ページング対応）
• esacreatepost - 新しい記事を作成（タグ、カテゴリー、WIP ステータス付き）
• esaupdatepost - 記事を更新（タイトル、本文、タグ、カテゴリー、WIP ステータス）
• esaappendpost - 記事本文の末尾に追記（既存本文を取得せずに追記でき、新しいリビジョンとして保存）
• esaprependpost - 記事本文の先頭に追記（既存本文を取得せずに追記でき、新しいリビジョンとして保存）

記事の操作

• esaarchivepost - 記事をアーカイブ（Archived/ カテゴリーへ移動）
• esashippost - 記事を Ship It!（WIP を外して公開）
• esaduplicatepost - 記事を複製（同じタイトル・本文の WIP 記事を作成。別チームへの複製も可能）

コメント管理

• esagetcomment - コメント ID からコメントを取得
• esacreatecomment - 記事にコメントを追加
• esaupdatecomment - コメントを編集
• esadeletecomment - コメントを削除
• esagetpost_comments - 記事のコメント一覧（ページング対応）
• esagetteam_comments - チーム全体のコメント一覧（ページング対応）

カテゴリー管理

• esagetcategories - 指定パス配下のカテゴリー一覧
• esagettop_categories - トップレベルのカテゴリー一覧
• esagetallcategorypaths - チーム内の全カテゴリーパス一覧（記事数付き、フィルタリング対応）
• カテゴリ構造の把握、整理、統合の計画に最適
• フィルター例: prefix: "dev" で開発関連、match: "api" で API 関連を検索

添付ファイル

• esagetattachment - 記事やコメントの添付ファイルを取得
• サポート形式（JPEG, PNG, GIF, WebP）で 30MB 以下の画像は base64 エンコードで返却
• その他のファイル、大きな画像、または forceSignedUrl 指定時は署名付き URL（有効期限 5 分）を返却

ヘルプとドキュメント

• esagetsearchoptionshelp - esa の検索構文ヘルプ
• esagetmarkdownsyntaxhelp - esa の Markdown 記法ヘルプ
• esasearchhelp - esa のドキュメントから機能や用語を検索

リソース

• esarecentposts - 最近更新された記事の一覧
• テンプレート: esa://teams/{teamName}/posts/recent
• 戻り値: 最近更新された記事の JSON リスト

プロンプト

• esasummarizepost - esa の記事を要約
• 入力: チーム名と記事 ID
• 出力: 記事の構造化された要約

MCP クライアントの設定

MCP クライアントの設定ファイルに以下を追加します：

用意する環境変数

• ESAACCESSTOKEN: アクセストークン
• 必要なスコープ: read write または admin:comment read:post write:post read:category read:tag read:attachment read:team read:member
• PAT v2を推奨します。
• LANG: UI の言語設定

Claude Desktop の例

claudedesktopconfig.json への追加方法：

オプション 1: docker(推奨)

{
  "mcpServers": {
    "esa": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ESA_ACCESS_TOKEN",
        "-e",
        "LANG",
        "ghcr.io/esaio/esa-mcp-server"
      ],
      "env": {
        "ESA_ACCESS_TOKEN": "your_personal_access_token",
        "LANG": "ja"
      }
    }
  }
}

オプション 2: npx

{
  "mcpServers": {
    "esa": {
      "command": "/Users/your-username/.nodenv/shims/npx",
      "args": ["@esaio/esa-mcp-server"],
      "env": {
        "ESA_ACCESS_TOKEN": "your_personal_access_token",
        "LANG": "ja"
      }
    }
  }
}

注意: /path/to/your/node は which node で調べたパスに置き換えてください。

レジストリ

このパッケージはルート直下に registry.json を同梱しており、登録されているツール / リソース / プロンプトの一覧を公開しています。サーバーを起動せずにプログラムから読み取れます:

import registry from "@esaio/esa-mcp-server/registry.json" with { type: "json" };

スキーマ:

{
  "tools": [{ "name": "esa_get_teams" }, "..."],
  "resources": [
    { "name": "esa_recent_posts", "uriTemplate": "esa://teams/{teamName}/posts/recent" }
  ],
  "prompts": [{ "name": "esa_summarize_post" }]
}

registry.json は npm run build:registry で生成され、登録内容と差分が出ると CI で fail します。

リンク

Shortened. The full README is on GitHub.