MCP SERVER · OFFICIAL PROJECTWork a team's esa.io knowledge base — search it, append to a running post, ship a draft, archive or roll one back — without leaving the editor.
LABSCO SUMMARY
esa_append_post and esa_prepend_post write a new revision from the content alone, which makes a daily log or a meeting record a single call rather than a fetch-modify-replace cycle, and esa_rollback_post_revision means a bad write is a revision number away from being undone. Two of the 28 tools return esa's own search and Markdown grammar, so a complex query is built from the documented syntax rather than guessed at.
An esa.io client of 28 tools covering teams and their statistics, posts and revisions, comments, categories and tags, and the search and Markdown references the model can consult before writing a query.
An esa access token and the team name that nearly every call takes. npx on your PATH.
One command plus a key — npx @esaio/esa-mcp-server, then supply credentials
USE CASES
Appending saves a new revision from the content alone, without reading the existing body first, which makes a daily entry one call. Prepending does the same at the top for logs that read newest-first.
Ask for esa's search grammar first and the query can use date ranges and the rest of the syntax properly instead of degrading into a keyword guess. Backlinks then show which posts point at what you found.
Posts carry a WIP flag rather than living in a separate drafts area, so publishing is clearing that flag. Updating content and shipping in the same call is one operation; shipping alone is the other.
Every category path with its post count shows where the duplicates and near-duplicates are — the paths with two posts that should have been folded into the one with forty. Archiving moves a post under Archived/ rather than deleting it.
Every write is a revision, so an overwrite is undone by rolling back to the revision number before it — and the rollback is itself saved as a new revision, leaving the history intact.
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
esa_append_postAppends Markdown content to the end of an existing post's body, saving it as a new revision. Unlike esa_update_post, this does not require fetching the current body first, making it ideal for adding to a post (e.g. log entries, meeting notes). Optionally set wip to change the WIP state.
esa_archive_postArchives 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_create_commentCreates a new comment on an existing post in an esa team.
esa_create_postCreates a new post in an esa team with optional tags, category, and WIP status.
esa_delete_commentDeletes a comment from an esa team by comment ID.
esa_duplicate_postDuplicates a post by creating a new WIP post with the same name and body_md as the source post. By default the duplicate is created in the source team; specify targetTeamName to duplicate into a different team.
esa_get_all_category_pathsRetrieves category paths in a team to understand the overall category structure. Perfect for category organization, cleanup, migration planning, or finding similar categories. Returns a paginated list of paths with post counts, sorted in lexicographic order. Supports filtering (prefix/suffix/match/exact_match) to find categories by pattern.
esa_get_attachmentRetrieves an attachment file from esa with signed URLs. For supported images (JPEG, PNG, GIF, WebP) under 30MB, returns base64-encoded data. For other file types, larger images, or when forceSignedUrl is true, returns signed URLs.
esa_get_categoriesRetrieves category information and subcategories for a specific category path, with optional posts and parent categories included
esa_get_commentRetrieves a specific comment by comment ID, with optional stargazers included.
esa_get_markdown_syntax_helpGet 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_get_postRetrieves a specific post from an esa team by post number. The response always includes backlinks_count (the number of posts referencing this one). To list the referencing posts themselves, use esa_get_post_backlinks. To fetch comments, use esa_get_post_comments.
esa_get_post_backlinksRetrieves a paginated list of posts that reference (link back to) the specified post. Archived posts and WIP posts are excluded. Results are ordered by backlink registration date (newest references first).
esa_get_post_commentsRetrieves a list of comments for a specific post with pagination support.
esa_get_search_options_helpGet 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_team_commentsRetrieves a list of comments in a team with pagination support.
esa_get_team_membersRetrieves all members of a team with their roles and profile information
esa_get_team_statsRetrieves team statistics including member count, posts count (total/WIP/shipped), comments, stars, watches, and daily/weekly/monthly active users
esa_get_team_tagsRetrieves all tags used in posts within a team, along with the count of posts for each tag
esa_get_teamsRetrieves a list of esa teams that the user has access to.
esa_get_top_categoriesRetrieves all top-level categories for a team
esa_prepend_postPrepends Markdown content to the beginning of an existing post's body, saving it as a new revision. Unlike esa_update_post, this does not require fetching the current body first. Behaves the same as esa_append_post except content is inserted at the start of the body. Optionally set wip to change the WIP state.
esa_rollback_post_revisionRolls back a post to the specified revision, saving the restored content as a new revision.
esa_search_helpSearch 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.
esa_search_postsSearch for posts in esa.io
esa_ship_postShips 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_update_commentUpdates an existing comment in an esa team by comment ID.
esa_update_postUpdates 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. To only add content to the start or end of the body, use esa_append_post or esa_prepend_post instead.
BEFORE YOU INSTALL
28 tools when we connected. esa_rollback_post_revision, which restores an earlier post revision, is undocumented. esa_recent_posts is a resource and esa_summarize_post a prompt; neither can be called as a tool.
Both documented setups run the server on your machine.
CONTEXT COST
Rated by the size of the 28 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
npx @esaio/esa-mcp-server{
"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_ESA_ACCESS_TOKEN>",
"LANG": "ja"
}
}
}
}{
"mcpServers": {
"esa": {
"command": "/Users/<YOUR_USERNAME>/.nodenv/shims/npx",
"args": [
"@esaio/esa-mcp-server"
],
"env": {
"ESA_ACCESS_TOKEN": "<YOUR_ESA_ACCESS_TOKEN>",
"LANG": "ja"
}
}
}
}/Users/<YOUR_USERNAME>/.nodenv/shims/npx is the path which npx prints on your machine — the example is a nodenv shim in its author's home folder —.
MCP servers
koki-develop
makenotion
d-kimuson
scnsh