esa MCP Server

official

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

GitHub
61

What can you do with Esa MCP?

  • List your esa teams and team stats — Use esa_get_teams and esa_get_team_stats to see which teams you can access and their activity metrics.
  • Search and retrieve esa posts — Find posts with esa_search_posts, then get full content and metadata with esa_get_post.
  • Create, update, or append to posts — Draft new posts via esa_create_post, modify existing ones with esa_update_post, or add content without fetching the current body using esa_append_post / esa_prepend_post.
  • Manage post workflow states — Archive posts with esa_archive_post, mark them as shipped via esa_ship_post, or duplicate them across teams using esa_duplicate_post.
  • Work with comments — List, create, update, or delete comments on posts using esa_get_post_comments, esa_create_comment, esa_update_comment, and esa_delete_comment.
  • Browse categories and tags — Explore team category structures with esa_get_all_category_paths and esa_get_categories, or review all tags via esa_get_team_tags.

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)

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