esa MCP Server

ทางการ

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

GitHub

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)

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