esa MCP Server

# esa MCP Server <img width="775" alt="スクリーンショット 2025-03-27 午後1 14 09" src="https://github.com/user-attachments/assets/e5f8f308-ed7a-4774-b3a3-9cc284ea7422" /> *Read this in [Japanese](README.ja.md)* ## Overview This server is an interface that uses the [Model Context Protocol (MCP)](https://github.com/anthropics/anthropic-cookbook/tree/main/model_context_protocol) to enable Claude AI to interact with the [esa API](https://docs.esa.io/posts/102). With this MCP server, Claude AI can perform operations such as searching, creating, and updating esa documents. <a href="https://glama.ai/mcp/servers/@kajirita2002/esa-mcp-server"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@kajirita2002/esa-mcp-server/badge" alt="esa Server MCP server" /> </a> ## About the Repository This repository provides a standalone implementation of the esa MCP server. It integrates Claude AI with esa to streamline document management. ## Setup ### Prerequisites - Node.js 18 or higher - esa API access token - esa team name ### Installation ```bash # Install globally npm install -g @kajirita2002/esa-mcp-server # Or use directly with npx npx @kajirita2002/esa-mcp-server ``` ### Setting Environment Variables ```bash # Set environment variables export ESA_ACCESS_TOKEN="your_esa_access_token" export ESA_TEAM="your_team_name" ``` ### MCP Configuration Example If you're using this MCP server, add the following configuration to your `mcp_config.json` file: ```json "esa": { "command": "npx", "args": ["-y", "@kajirita2002/esa-mcp-server"], "env": { "ESA_ACCESS_TOKEN": "your_esa_access_token", "ESA_TEAM": "your_team_name" } } ``` ### Starting the Server ```bash # Start the server npm start ``` ## Available Tools This MCP server provides the following tools: ### Post Related 1. `esa_list_posts` - Get a list of posts in the team - Input: - `q` (string, optional): Search query - `include` (string, optional): Related data to include in the response (e.g. 'comments,stargazers') - `sort` (string, optional): Sort method (updated, created, number, stars, watches, comments, best_match) - `order` (string, optional): Sort order (desc, asc) - `per_page` (number, optional): Number of results per page (max: 100) - `page` (number, optional): Page number to retrieve 2. `esa_get_post` - Get detailed information about a specific post - Input: - `post_number` (number, required): Post number to retrieve - `include` (string, optional): Related data to include in the response (e.g. 'comments,stargazers') 3. `esa_create_post` - Create a new post - Input: - `name` (string, required): Post title - `body_md` (string, optional): Post body (Markdown format) - `tags` (array of string, optional): List of tags for the post - `category` (string, optional): Post category - `wip` (boolean, optional, default: true): Whether to mark as WIP (Work In Progress) - `message` (string, optional): Change message - `user` (string, optional): Poster's screen_name (only team owners can specify) - `template_post_id` (number, optional): ID of the post to use as a template 4. `esa_update_post` - Update an existing post - Input: - `post_number` (number, required): Post number to update - `name` (string, optional): New title for the post - `body_md` (string, optional): New body for the post (Markdown format) - `tags` (array of string, optional): New list of tags for the post - `category` (string, optional): New category for the post - `wip` (boolean, optional): Whether to mark as WIP (Work In Progress) - `message` (string, optional): Change message - `created_by` (string, optional): Poster's screen_name (only team owners can specify) - `original_revision` (string, optional): Revision to base the update on ### Comment Related 1. `esa_list_comments` - Get a list of comments for a post - Input: - `post_number` (number, required): Post number to get comments for - `page` (number, optional): Page number to retrieve - `per_page` (number, optional): Number of results per page (max: 100) 2. `esa_get_comment` - Get a specific comment - Input: - `comment_id` (number, required): ID of the comment to retrieve - `include` (string, optional): Related data to include in the response (e.g. 'stargazers') 3. `esa_create_comment` - Post a comment to an article - Input: - `post_number` (number, required): Post number to comment on - `body_md` (string, required): Comment body (Markdown format) - `user` (string, optional): Poster's screen_name (only team owners can specify) ### Member Related 1. `esa_get_members` - Get a list of team members - Input: - `page` (number, optional): Page number to retrieve - `per_page` (number, optional): Number of results per page (max: 100) 2. `esa_get_member` - Get information about a specific team member - Input: - `screen_name_or_email` (string, required): Screen name or email of the member to retrieve ## Usage Example Here's an example of Claude using this MCP server to create an esa post: ``` [Claude] Please create a new post in esa. The title should be "Project X Progress Report" and the body should include "# This Week's Progress\n\n- Implementation of Feature A completed\n- Testing of Feature B started\n\n## Next Week's Plan\n\n- Start implementation of Feature C". [MCP Server] Using the esa_create_post tool to create a new post. [Result] { "number": 123, "name": "Project X Progress Report", "body_md": "# This Week's Progress\n\n- Implementation of Feature A completed\n- Testing of Feature B started\n\n## Next Week's Plan\n\n- Start implementation of Feature C", "wip": false, "created_at": "2023-06-01T12:34:56+09:00", "updated_at": "2023-06-01T12:34:56+09:00", "url": "https://your-team.esa.io/posts/123" } [Claude] The post has been created successfully. The post number is 123, and you can access it at the following URL: https://your-team.esa.io/posts/123 ``` ## Troubleshooting ### Access Token Issues ``` Error: Request failed with status code 401 ``` If you see this error, your esa access token may be invalid or expired. Generate a new access token from the esa settings screen and update your environment variable. ### Permission Issues ``` Error: Request failed with status code 403 ``` If you see this error, the current access token doesn't have the necessary permissions. Check the permissions for your access token in the esa settings screen and issue a new token if needed. ## License Provided under the MIT License.