esa-mcp-server

重要

An official MCP server has been released. Please use the official server going forward.

• esa公式のローカルMCPサーバーを公開しました - ReleaseNotes/2025/09/17 - docs.esa.io

esa MCP Server

A Model Context Protocol (MCP) server for esa.io.

Table of Contents

• Usage
  • Prerequisites
  • Configuration
    • Using npx
    • Using Docker
  • Read-only Mode
• MCP Tools
  • Posts
  • Tags
  • Comments
• License

Usage

Prerequisites

Before using this MCP server, you need to generate a personal access token from your esa.io team:

1. Go to https://<TEAM_NAME>.esa.io/user/applications
2. Create a new personal access token
3. Copy the token for configuration

Configuration

You can run the server either via npx or Docker.

Using npx

Add the following configuration to your MCP client:

{
  "mcpServers": {
    "esa": {
      "command": "npx",
      "args": [
        "-y",
        "@koki-develop/esa-mcp-server@latest"
      ],
      "env": {
        "ESA_TEAM": "<your-team-name>",
        "ESA_ACCESS_TOKEN": "<your-personal-access-token>"
      }
    }
  }
}

Replace <your-team-name> and <your-personal-access-token> with your team name and personal access token.

Using Docker

If you prefer Docker, use the following configuration:

{
  "mcpServers": {
    "esa": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ESA_TEAM",
        "-e",
        "ESA_ACCESS_TOKEN",
        "ghcr.io/koki-develop/esa-mcp-server:latest"
      ],
      "env": {
        "ESA_TEAM": "<your-team-name>",
        "ESA_ACCESS_TOKEN": "<your-personal-access-token>"
      }
    }
  }
}

Read-only Mode

To enable read-only mode that only allows read operations, add the --readonly flag.

Using npx:

{
  "mcpServers": {
    "esa": {
      "command": "npx",
      "args": [
        "-y",
        "@koki-develop/esa-mcp-server@latest",
        "--readonly"
      ],
      "env": {
        "ESA_TEAM": "<your-team-name>",
        "ESA_ACCESS_TOKEN": "<your-personal-access-token>"
      }
    }
  }
}

Using Docker:

{
  "mcpServers": {
    "esa": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ESA_TEAM",
        "-e",
        "ESA_ACCESS_TOKEN",
        "ghcr.io/koki-develop/esa-mcp-server:latest",
        "--readonly"
      ],
      "env": {
        "ESA_TEAM": "<your-team-name>",
        "ESA_ACCESS_TOKEN": "<your-personal-access-token>"
      }
    }
  }
}

In read-only mode, only the following operations are available:

• get_posts - retrieve posts
• get_post - retrieve a specific post
• get_tags - retrieve tags
• get_post_comments - retrieve post comments

Write operations (create_post, update_post, delete_post, create_post_comment, update_comment, delete_comment) are disabled.

MCP Tools

• Posts
• Tags
• Comments

Posts

Tool	Description
get_posts	Retrieve a list of posts from the esa team. Supports search queries, filtering, sorting, and pagination. Returns post metadata including title, content, tags, categories, author information, and engagement metrics (comments, stars, watches). Optionally includes comments and stargazers with the include parameter. Supports nested inclusion like 'comments,comments.stargazers'. Note: Post content (body_md) is truncated to 300 characters with a body_truncated field indicating if truncation occurred to reduce context size.
get_post	Retrieve a specific post from the esa team by post number. Returns complete post details including title, content (markdown), tags, category, author information, revision history, and engagement metrics. Optionally includes comments and stargazers. Supports nested inclusion like 'comments,comments.stargazers'.
create_post	Create a new post in the esa team. Requires a title and optionally accepts content, tags, category, WIP status, and other metadata. Returns the created post information including the assigned post number and URL.
update_post	Update an existing post in the esa team. Requires a post number and optionally accepts updated content, tags, category, WIP status, and other metadata. Returns the updated post information including revision details.
delete_post	Delete an existing post from the esa team. Requires a post number. The post will be permanently deleted and cannot be recovered. Returns a confirmation message upon successful deletion.

タグ

ツール	説明
get_tags	esa チームで使用されているすべてのタグの一覧を取得します。タグ名と、タグが付けられている投稿数を含み、投稿数の降順で並べ替えて返します。ページネーションに対応しています。

コメント

ツール	説明
get_post_comments	esa チームの特定の投稿に対するコメント一覧を取得します。投稿番号が必要で、ページネーションに対応しています。内容、投稿者情報、タイムスタンプ、エンゲージメント指標（スター）などのコメントメタデータを返します。
create_post_comment	esa チームの既存の投稿に新しいコメントを作成します。投稿番号と Markdown 形式のコメント内容が必要です。ID、内容、タイムスタンプ、投稿者の詳細など、作成したコメントの情報を返します。
update_comment	esa チームの投稿にある既存のコメントを更新します。コメント ID と Markdown 形式の新しい内容が必要です。内容、タイムスタンプ、投稿者の詳細など、更新したコメントの情報を返します。
delete_comment	esa チームから既存のコメントを削除します。コメント ID が必要です。コメントは完全に削除され、復元できません。削除が成功すると確認メッセージを返します。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

Copyright (c) 2025 Koki Sato