mcp-esa-server-python

esa.io API と連携するための Model Context Protocol Server (mcp server)です。Pythonで実装しています。

できること

現在は以下の機能を提供しています。

ユーザー情報取得（user_get_info）
記事一覧取得（posts_get_list）
記事詳細取得（posts_get_detail）
記事作成 (posts_create)
記事更新 (posts_update)
記事削除 (posts_delete)

セットアップ手順

前提条件

esa.ioのAPIトークンを発行済であること
uv が使えること
インターネット接続
esa.ioのAPIトークンの発行方法
- あなたの esa.io チームのページにアクセスします (例: https://<your-team-name>.esa.io/)。
- 左カラムのSETTINGSをクリックし、「ユーザー設定」>「外部アプリ連携」を選択します。
- 「Personal access tokens」セクションで、「Generate new token」をクリックします。
- トークン名 (例: mcp-server) を入力し、必要な権限スコープを選択します。この MCP サーバーには少なくとも以下の権限が必要です:
  - read (記事の読み取り)
  - write (記事の作成・更新・削除)
  - read_user (ユーザー情報の取得) （この項目は自動的に有効になるため、表示されない可能性があります）
- 「Save」をクリックします。
- 表示されたトークンを必ずコピーして安全な場所に保管してください。このトークンは一度しか表示されません。
- コピーしたトークンは、後述の .env ファイルの ESA_TOKEN の値として貼り付けます。
esa.io では、サインアップから2ヶ月間の無料トライアル期間が提供されています。この期間を利用して、テスト用のチーム名とAPIトークンを取得することができます。
セキュリティのため、トークンは直接公開しないようご注意ください。

プロジェクトの初期化

uv sync

開発(ローカルでの使い方)

開発に参加する場合や、MCPInspectorを利用する場合は、以下の手順で環境を構築します。

環境変数の設定 .env.example を参考にして、.env をサーバーを実行したいディレクトリ(.env.exampleと同じ場所)を作成します。

ESA_TEAM_NAME="YOUR_ESA_TEAM_NAME" # Replace with your esa.io team name (e.g., "myteam")
ESA_TOKEN="YOUR_ESA_API_TOKEN"     # Replace with your esa.io API access token

実行方法下記コマンドを実行後に、指示のあるURLからブラウザを開くことで、MCP Inspectorを使って、各コマンド(記事作成など)を実行することができます。
```
uv run mcp run main.py
```

MCPServerとしてCursorエディタで使う方法

mcp.jsonの作成例

プロジェクトルートまたは ~/.cursor/mcp.json に以下のような設定ファイルを用意します。

{
  "mcpServers": {
    "mcp-esa-server": {
      "command": "uv",
      "args": [
        "--directory",
        "<プロジェクトの絶対パス>",
        "run",
        "main.py"
      ],
      "env": {
        "ESA_TEAM_NAME": "<your-team-name>",
        "ESA_TOKEN": "<your-esa-token>"
      }
    }
  }
}

<your-team-name> と <your-esa-token> は各自のesa.ioチーム名・APIトークンに置き換えてください。
env: 環境変数を直接設定します。この方法を使用する場合、.cursor/mcp.json のコミットは絶対に避けてください。

CursorエディタでMCPサーバーを起動

CursorエディタのコマンドパレットやUIから「MCPサーバーを起動」または「AIツールを有効化」します。
mcp.jsonの設定に従い、uv run main.py でサーバーが起動します。
.env ファイルや環境変数も自動的に読み込まれます。

AIチャットやツールパネルからAPIを呼び出し

AIチャット上で user_get_info や posts_get_list などのMCPツールを呼び出すことで、esa.io APIと連携した操作が可能です。
mcp-esa-serverを使って記事の作成をお願いします などとチャット上で書き込むことで利用できます。

ライセンス (License)

このプロジェクトは MIT License の下で公開されています。

使用している外部コード / Dependencies

このプロジェクトの一部では、以下のMIT Licenseで公開されているコードを参照しています。

esa-mcp-server
- GitHubリポジトリ: [https://github.com/masseater/esa-mcp-server]
- ライセンス: MIT License

その他 (Misc)

生成元 (Generated by)

generated by Cursor (gemini-2.5-pro-exp-03-25)

セットアップ手順

前提条件

esa.ioのAPIトークンを発行済であること

uv が使えること

インターネット接続

esa.ioのAPIトークンの発行方法

あなたの esa.io チームのページにアクセスします (例: https://<your-team-name>.esa.io/)。
左カラムのSETTINGSをクリックし、「ユーザー設定」>「外部アプリ連携」を選択します。
「Personal access tokens」セクションで、「Generate new token」をクリックします。
トークン名 (例: mcp-server) を入力し、必要な権限スコープを選択します。この MCP サーバーには少なくとも以下の権限が必要です:
- read (記事の読み取り)
- write (記事の作成・更新・削除)
- read_user (ユーザー情報の取得) （この項目は自動的に有効になるため、表示されない可能性があります）
「Save」をクリックします。
表示されたトークンを必ずコピーして安全な場所に保管してください。このトークンは一度しか表示されません。
コピーしたトークンは、後述の .env ファイルの ESA_TOKEN の値として貼り付けます。

esa.io では、サインアップから2ヶ月間の無料トライアル期間が提供されています。この期間を利用して、テスト用のチーム名とAPIトークンを取得することができます。

セキュリティのため、トークンは直接公開しないようご注意ください。

プロジェクトの初期化

uv sync

開発(ローカルでの使い方)

開発に参加する場合や、MCPInspectorを利用する場合は、以下の手順で環境を構築します。

環境変数の設定 .env.example を参考にして、.env をサーバーを実行したいディレクトリ(.env.exampleと同じ場所)を作成します。

ESA_TEAM_NAME="YOUR_ESA_TEAM_NAME" # Replace with your esa.io team name (e.g., "myteam")
ESA_TOKEN="YOUR_ESA_API_TOKEN"     # Replace with your esa.io API access token

実行方法下記コマンドを実行後に、指示のあるURLからブラウザを開くことで、MCP Inspectorを使って、各コマンド(記事作成など)を実行することができます。

uv run mcp run main.py

MCPServerとしてCursorエディタで使う方法

mcp.jsonの作成例

プロジェクトルートまたは ~/.cursor/mcp.json に以下のような設定ファイルを用意します。

{ "mcpServers": { "mcp-esa-server": { "command": "uv", "args": [ "--directory", "<プロジェクトの絶対パス>", "run", "main.py" ], "env": { "ESA_TEAM_NAME": "<your-team-name>", "ESA_TOKEN": "<your-esa-token>" } } } }

<your-team-name> と <your-esa-token> は各自のesa.ioチーム名・APIトークンに置き換えてください。

env: 環境変数を直接設定します。この方法を使用する場合、.cursor/mcp.json のコミットは絶対に避けてください。

CursorエディタでMCPサーバーを起動

CursorエディタのコマンドパレットやUIから「MCPサーバーを起動」または「AIツールを有効化」します。

mcp.jsonの設定に従い、uv run main.py でサーバーが起動します。

.env ファイルや環境変数も自動的に読み込まれます。

AIチャットやツールパネルからAPIを呼び出し

AIチャット上で user_get_info や posts_get_list などのMCPツールを呼び出すことで、esa.io APIと連携した操作が可能です。

mcp-esa-serverを使って記事の作成をお願いします などとチャット上で書き込むことで利用できます。