# 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](https://esa.io/) では、サインアップから2ヶ月間の無料トライアル期間が提供されています。この期間を利用して、テスト用のチーム名とAPIトークンを取得することができます。
- セキュリティのため、トークンは直接公開しないようご注意ください。
### プロジェクトの初期化
```bash
uv sync
```
### 開発(ローカルでの使い方)
開発に参加する場合や、MCPInspectorを利用する場合は、以下の手順で環境を構築します。
1. 環境変数の設定
`.env.example` を参考にして、`.env` をサーバーを実行したいディレクトリ(`.env.example`と同じ場所)を作成します。
```dotenv
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を使って、各コマンド(記事作成など)を実行することができます。
```bash
uv run mcp run main.py
```
### MCPServerとしてCursorエディタで使う方法
1. **mcp.jsonの作成例**
プロジェクトルートまたは `~/.cursor/mcp.json` に以下のような設定ファイルを用意します。
```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)
