esa MCP Server

official

Official Model Context Protocol (MCP) server for esa.io - STDIO transport version.

What can you do with Esa MCP?

  • Search and read posts — Find posts with esa_search_posts, then fetch a specific one by number with esa_get_post to see its backlink count and body stats.
  • Create and edit content — Create posts with esa_create_post, update them with esa_update_post, or append and prepend text using esa_append_post and esa_prepend_post.
  • Manage post lifecycle — Ship a post with esa_ship_post, archive it with esa_archive_post, duplicate it with esa_duplicate_post, or roll back to an earlier revision.
  • Handle comments — List comments on a post or team, then create, update, or delete them with esa_create_comment, esa_update_comment, and esa_delete_comment.
  • Explore categories and teams — Browse category paths with esa_get_all_category_paths and check team details with esa_get_team_stats and esa_get_team_members.
  • Summarize a post — Use the esa_summarize_post prompt to get a structured summary of a given team's post.

Documentation

esa MCP Server

License: MIT

日本語 | English

Official Model Context Protocol (MCP) server for esa.io - STDIO transport version.

Overview

This MCP server provides seamless integration between AI assistants and esa.io, a collaborative documentation platform. It enables AI assistants to read, create, update, and manage esa documents directly through the Model Context Protocol.

Available Tools

Team Management

  • esa_get_teams - Get user's accessible esa teams
  • esa_get_team_stats - Get team statistics (members, posts, comments, stars, watches, active users)
  • esa_get_team_tags - Get all tags used in team posts with count
  • esa_get_team_members - Get team members with roles and profile information

Post Management

  • esa_search_posts - Search for posts in esa.io
  • esa_get_post - Get a specific post by post number (includes backlinks_count and body_md_stats with the body's character and line counts)
  • esa_get_post_backlinks - List posts that reference a specific post with pagination
  • esa_create_post - Create a new post with tags, category, and WIP status
  • esa_update_post - Update existing post (title, content, tags, category, WIP status)
  • esa_append_post - Append content to the end of a post's body (no need to fetch the current body; saved as a new revision)
  • esa_prepend_post - Prepend content to the beginning of a post's body (no need to fetch the current body; saved as a new revision)

Post Actions

  • esa_archive_post - Archive a post by moving to Archived/ category
  • esa_ship_post - Ship a post (mark as complete by setting wip to false)
  • esa_duplicate_post - Duplicate a post (create a new WIP post with the same title and body; cross-team duplication is also supported)
  • esa_rollback_post_revision - Roll back a post to a specified revision (the restored content is saved as a new revision; check the revision number via revision_number in esa_get_post)

Comment Management

  • esa_get_comment - Get a specific comment by ID
  • esa_create_comment - Create a new comment on a post
  • esa_update_comment - Update an existing comment
  • esa_delete_comment - Delete a comment
  • esa_get_post_comments - Get comments for a specific post with pagination
  • esa_get_team_comments - Get team comments with pagination

Category Management

  • esa_get_categories - Get categories and subcategories for a specific path
  • esa_get_top_categories - Get all top-level categories for a team
  • esa_get_all_category_paths - Get all category paths in a team (with post counts, supports filtering)
    • Perfect for understanding category structure, organization planning, and cleanup
    • Filter examples: prefix: "dev" for development-related, match: "api" for API-related categories

Attachments

  • esa_get_attachment - Retrieve an attachment file from esa posts and comments
    • Returns base64-encoded data for supported images (JPEG, PNG, GIF, WebP) under 30MB
    • Returns signed URLs (valid for 5 minutes) for other file types, larger images, or when forceSignedUrl is specified

Help & Documentation

  • esa_get_search_options_help - Get esa search syntax documentation
  • esa_get_markdown_syntax_help - Get esa Markdown syntax documentation
  • esa_search_help - Search esa documentation for features and terminology

Available Resources

  • esa_recent_posts - Fetch recent updated posts from esa team
    • Template: esa://teams/{teamName}/posts/recent
    • Returns: JSON list of recently updated posts

Available Prompts

  • esa_summarize_post - Summarize an esa post content
    • Input: Team name and post number
    • Output: Structured summary of the post content

MCP Client Configuration

Add to your MCP client configuration file:

Required Environment Variables

  • ESA_ACCESS_TOKEN: Access Token
    • Required scopes: read write or admin:comment read:post write:post read:category read:tag read:attachment read:team read:member
    • PAT v2 is recommended.
  • LANG: Language for UI

Claude Desktop Example

Add to claude_desktop_config.json:

Option 1: Docker (Recommended)

{
  "mcpServers": {
    "esa": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ESA_ACCESS_TOKEN",
        "-e",
        "LANG",
        "ghcr.io/esaio/esa-mcp-server"
      ],
      "env": {
        "ESA_ACCESS_TOKEN": "your_personal_access_token",
        "LANG": "en"
      }
    }
  }
}

Option 2: npx

{
  "mcpServers": {
    "esa": {
      "command": "/Users/your-username/.nodenv/shims/npx",
      "args": ["@esaio/esa-mcp-server"],
      "env": {
        "ESA_ACCESS_TOKEN": "your_personal_access_token",
        "LANG": "en"
      }
    }
  }
}

Note: Replace /path/to/your/node with the output of which node command.

Registry

This package ships registry.json at the package root, exposing registered tools, resources, and prompts. It can be consumed programmatically without spawning the server:

import registry from "@esaio/esa-mcp-server/registry.json" with {
  type: "json",
};

Schema:

{
  "tools": [{ "name": "esa_get_teams" }, "..."],
  "resources": [
    {
      "name": "esa_recent_posts",
      "uriTemplate": "esa://teams/{teamName}/posts/recent"
    }
  ],
  "prompts": [{ "name": "esa_summarize_post" }]
}

The file is regenerated by npm run build:registry and a CI check enforces that it stays in sync with the registered set.

Links

Support


Made with ❤️ by the esa team