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を利用する場合は、以下の手順で環境を構築します。

1. 環境変数の設定 .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

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

   uv run mcp run main.py

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

1. 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 のコミットは絶対に避けてください。

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

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

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

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

ライセンス (License)

このプロジェクトは MIT License の下で公開されています。 (注: 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)