# esa [Health: Active]

**Category:** 🏢 Workplace & Productivity  
**Repository:** https://github.com/esaio/esa-mcp-server  
**GitHub Stars:** 62  
**npm Downloads (last month):** 34909  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/esa

## Description
Official MCP server for esa.io - a documentation sharing service for teams

## Tools
Capabilities this server exposes over MCP:

- **esa_get_teams** — Retrieves a list of esa teams that the user has access to.
- **esa_get_team_stats** — Retrieves team statistics including member count, posts count (total/WIP/shipped), comments, stars, watches, and daily/weekly/monthly active users
- **esa_get_team_tags** — Retrieves all tags used in posts within a team, along with the count of posts for each tag
- **esa_get_team_members** — Retrieves all members of a team with their roles and profile information
- **esa_get_post** — Retrieves a specific post from an esa team by post number, with optional comments included.
- **esa_search_posts** — Search for posts in esa.io
- **esa_create_post** — Creates a new post in an esa team with optional tags, category, and WIP status.
- **esa_update_post** — Updates an existing post in an esa team by post number. You can update the title, content, tags, category, and WIP status. To ship a post (mark as complete), set wip to false - this is preferred over using esa_ship_post when updating other fields simultaneously.
- **esa_get_comment** — Retrieves a specific comment by comment ID, with optional stargazers included.
- **esa_create_comment** — Creates a new comment on an existing post in an esa team.
- **esa_update_comment** — Updates an existing comment in an esa team by comment ID.
- **esa_delete_comment** — Deletes a comment from an esa team by comment ID.
- **esa_get_post_comments** — Retrieves a list of comments for a specific post with pagination support.
- **esa_get_team_comments** — Retrieves a list of comments in a team with pagination support.
- **esa_get_categories** — Retrieves category information and subcategories for a specific category path, with optional posts and parent categories included
- **esa_get_top_categories** — Retrieves all top-level categories for a team
- **esa_archive_post** — Archives a post by moving it to the Archived/ category. If the post is in 'dev/docs', it becomes 'Archived/dev/docs'. Posts without category go to 'Archived'.
- **esa_ship_post** — Ships a post by setting wip to false. This marks the post as complete and ready to be published. Use this only when you need to ship without making other changes - if you're also updating title, content, or other fields, use esa_update_post with wip: false instead.
- **esa_duplicate_post** — Prepares a post for duplication by retrieving its name and body_md content. Returns the name and body_md that can be used with esa_create_post to create a duplicate of the original post.
- **esa_get_search_options_help** — Get esa search syntax documentation when you need to construct complex
search queries. Use this BEFORE esa_search_posts if you're unsure how to
translate user's search requirements into proper esa query syntax (e.g., date
ranges, tag filters, category searches, advanced operators).
- **esa_get_markdown_syntax_help** — Get esa Markdown and formatting documentation when unsure about syntax.
Use this BEFORE using any tools with *_md parameters (like esa_create_post,
esa_update_post, esa_create_comment, esa_update_comment) if you need
clarification on Markdown syntax, esa-specific extensions, or formatting options.
- **esa_search_help** — Search esa documentation for features, terminology, and specifications.
Use this when users mention esa-specific terms, ask about esa functionality,
or request help with esa workflows that you're not familiar with.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "esa": {
    "command": "npx",
    "args": ["-y","@esaio/esa-mcp-server"],
    "env": {
      "ESA_ACCESS_TOKEN": "",
      "LANG": ""
    }
  }
}
```

**Requires environment variables:** `ESA_ACCESS_TOKEN`, `LANG` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What esa MCP server does

The esa MCP server gives MCP-compatible assistants access to documentation and collaboration data in esa.io. It can inspect teams, members, tags, statistics, categories, articles, comments, and attachments. It also supports changes to esa content, including creating and updating posts, adding or editing comments, archiving posts, publishing WIP posts with Ship It!, and duplicating posts within or across teams.

The server covers both individual records and broader team workflows. Assistants can search posts, inspect backlinks, list comments with pagination, review category paths with article counts, and retrieve recent posts through an MCP resource. The included summarization prompt takes a team and article ID and produces a structured summary.

## How it works

Communication uses the Model Context Protocol with the STDIO transport. The assistant invokes named tools that map to esa operations, such as `esa_search_posts`, `esa_get_post`, `esa_create_post`, and `esa_update_post`. Read and write behavior depends on the permissions granted to the esa access token.

Attachment handling varies by file type and size. JPEG, PNG, GIF, and WebP images up to 30 MB can be returned as base64 data. Other files, larger images, or requests that force signed URLs are returned as signed URLs with a five-minute validity period.

The package also includes `registry.json`, which lists its tools, resource, and prompt without requiring the server to start. The recent-posts resource uses the URI pattern `esa://teams/{teamName}/posts/recent`.

## Setup and configuration

The esa MCP server requires an `ESA_ACCESS_TOKEN`. The README recommends a PAT v2 token. The token must have either the broad `read write` scopes or the documented set of post, comment, category, tag, attachment, team, and member permissions needed by the operations you plan to use. `LANG` controls the interface language.

For Claude Desktop, configure the server as a STDIO process. The documented options run the published container image with Docker or launch the npm package with `npx`. In either case, pass `ESA_ACCESS_TOKEN` and optionally set `LANG`, such as `ja`. When using the npx option, configure the path to the Node executable available on your machine.

## Tools and capabilities

Available capability groups include:

- Team discovery: list teams, members, roles, profiles, statistics, and tag usage.
- Post operations: search, retrieve, create, update, append, prepend, archive, publish, duplicate, and inspect backlinks.
- Comment operations: retrieve, create, update, delete, and list comments for a post or team.
- Category operations: list top-level categories, inspect children, or filter all category paths by prefix or matching text.
- Help and media: search esa help, retrieve search and Markdown syntax guidance, and fetch attachments.

Appending or prepending text creates a new revision without first retrieving the existing article body. Post retrieval can include backlink totals and body character and line counts.

## Limitations and notes

The esa MCP server is focused on esa.io and requires a valid access token with suitable scopes. It is distributed as an STDIO server; the provided setup examples specifically document Docker, npx, and Claude Desktop rather than a hosted HTTP endpoint. Signed attachment URLs expire after five minutes, so clients should use them within that period.

Write operations can change shared team content, including deleting comments, archiving posts, publishing WIP posts, and duplicating articles. Configure token permissions and assistant workflows accordingly. The server’s category, comment, and backlink listings support pagination where documented, so clients may need to request additional pages for complete results.

_Full upstream README: https://allmcps.com/mcp/esa/readme_