MCP 服务器

mcp-esa-server-python

A Python-based MCP server that enables users to interact with the esa.io API for documentation management. It provides tools for retrieving user information and performing full CRUD operations on articles.

README

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