mcp-esa-server-python

# mcp-esa-server-python This is a Model Context Protocol Server (mcp server) implemented in Python to integrate with the esa.io API. ## Features Currently, the following functionalities are provided: - User information retrieval (user_get_info) - Article list retrieval (posts_get_list) - Article detail retrieval (posts_get_detail) - Article creation (posts_create) - Article update (posts_update) - Article deletion (posts_delete) ## Setup Instructions ### Prerequisites - You must have an esa.io API token issued. - You need to have `uv` available. - Internet connection is required. - How to issue an esa.io API token: - Access your esa.io team page (e.g., `https://<your-team-name>.esa.io/`). - Click on SETTINGS in the left column and select "User Settings" > "External App Integration". - In the "Personal access tokens" section, click "Generate new token". - Enter a token name (e.g., `mcp-server`) and select the necessary permission scopes. This MCP server requires at least the following permissions: - `read` (Read articles) - `write` (Create, update, and delete articles) - `read_user` (Retrieve user information) (This item may not be displayed as it is automatically enabled) - Click "Save". - **Make sure to copy the displayed token and store it in a safe place. This token will only be shown once.** - The copied token should be pasted as the value of `ESA_TOKEN` in the `.env` file mentioned later. - [esa.io](https://esa.io/) offers a 2-month free trial period from sign-up. You can use this period to obtain a test team name and API token. - For security reasons, please be careful not to expose the token directly. ### Project Initialization ```bash uv sync ``` ### Development (Using Locally) If you want to participate in development or use MCPInspector, set up the environment with the following steps. 1. Set environment variables Create a `.env` file in the directory where you want to run the server (the same location as `.env.example`), referring to `.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. How to run After executing the command below, open the browser from the provided URL to use MCP Inspector and execute various commands (such as article creation). ```bash uv run mcp run main.py ``` ### Using as MCPServer with Cursor Editor 1. **Example of creating mcp.json** Prepare a configuration file like the following in the project root or `~/.cursor/mcp.json`. ```json { "mcpServers": { "mcp-esa-server": { "command": "uv", "args": [ "--directory", "<absolute path of the project>", "run", "main.py" ], "env": { "ESA_TEAM_NAME": "<your-team-name>", "ESA_TOKEN": "<your-esa-token>" } } } } ``` - Replace `<your-team-name>` and `<your-esa-token>` with your respective esa.io team name and API token. - `env`: Set environment variables **directly**. **If you use this method, please avoid committing `.cursor/mcp.json`.** 2. **Starting the MCP server in Cursor Editor** - Start the "MCP Server" or "Enable AI Tools" from the command palette or UI of the Cursor Editor. - Following the settings in mcp.json, the server will start with `uv run main.py`. - The `.env` file and environment variables will also be automatically loaded. 3. **Calling APIs from AI chat or tool panel** - You can call MCP tools like `user_get_info` or `posts_get_list` in the AI chat to perform operations integrated with the esa.io API. - You can use it by typing something like `Please create an article using mcp-esa-server` in the chat. ## License This project is licensed under the [MIT License](./LICENSE). ## External Code / Dependencies This project references code released under the MIT License in some parts. - **esa-mcp-server** - GitHub Repository: [https://github.com/masseater/esa-mcp-server] - License: MIT License ## Misc ### Generated by generated by Cursor (gemini-2.5-pro-exp-03-25)