Esa.io

Access the esa.io API to manage your team's knowledge base.

GitHub

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 のコミットは絶対に避けてください。
  1. CursorエディタでMCPサーバーを起動
  • CursorエディタのコマンドパレットやUIから「MCPサーバーを起動」または「AIツールを有効化」します。
  • mcp.jsonの設定に従い、uv run main.py でサーバーが起動します。
  • .env ファイルや環境変数も自動的に読み込まれます。
  1. AIチャットやツールパネルからAPIを呼び出し
  • AIチャット上で user_get_info や posts_get_list などのMCPツールを呼び出すことで、esa.io APIと連携した操作が可能です。
  • mcp-esa-serverを使って記事の作成をお願いします などとチャット上で書き込むことで利用できます。

ライセンス (License)

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

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

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

その他 (Misc)

生成元 (Generated by)

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

İlgili Sunucular