# esa

> esa is an open-source MCP server for knowledge and memory. Official MCP server for esa.io, the team documentation service, with posts and comments. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Repository:** https://github.com/esaio/esa-mcp-server
- **MCP Registry name:** io.github.esaio/esa
- **Categories:** [knowledge and memory](https://ai-powered.com/categories/knowledge-and-memory), [productivity](https://ai-powered.com/categories/productivity)
- **Listing updated:** 2026-11-18

## About

The server is published by the esa team and runs locally over stdio, from npm or a container image, using an esa access token with read and write scopes (the README recommends a personal access token v2). A LANG setting controls the interface language. The README is written in Japanese with an English version linked.

Beyond reading and searching articles, it can create, update, append to or prepend to posts without re-fetching the body, archive or ship a post, duplicate it (including to another team) and roll back to a prior revision. Comment tools cover create, edit, delete and listing, and category tools make it easy to map out and reorganise a team's category tree. Attachments under 30 MB in common image formats return as base64, while others return a five-minute signed URL.

It also exposes a recent-posts resource and a summarise-post prompt, and the package ships a registry.json listing its tools, resources and prompts. The code is MIT licensed.

## Features

- **Full post lifecycle:** Create, update, append, prepend, archive, ship, duplicate and roll back articles.
- **Comments:** Read, add, edit and delete comments on posts or across the team.
- **Category mapping:** List category paths with post counts, filtered by prefix or match.
- **Attachment retrieval:** Images up to 30 MB come back as base64, others as short-lived signed URLs.
- **Search help:** Built-in help tools for esa search syntax, Markdown syntax and docs.
- **Resource and prompt:** A recent-posts resource and a summarise-post prompt.

## Good for

- Search and summarise team documentation from an assistant
- Draft a new WIP article in a chosen category
- Append meeting notes to an existing post
- Plan a category reorganisation using path counts
- Review backlinks before archiving a post

## Install

### Claude Code (Terminal)

```sh
claude mcp add esa --env ESA_ACCESS_TOKEN='<ESA_ACCESS_TOKEN>' -- npx -y @esaio/esa-mcp-server
```

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "esa": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@esaio/esa-mcp-server"
      ],
      "env": {
        "ESA_ACCESS_TOKEN": "<ESA_ACCESS_TOKEN>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `esa_get_teams`: List your esa teams
- `esa_get_team_stats`: Team statistics
- `esa_get_team_tags`: Tags and usage counts
- `esa_get_team_members`: Members and roles
- `esa_search_posts`: Search articles
- `esa_get_post`: Get an article by ID
- `esa_get_post_backlinks`: List posts that reference an article
- `esa_create_post`: Create an article
- `esa_update_post`: Update an article
- `esa_append_post`: Append to an article body
- `esa_prepend_post`: Prepend to an article body
- `esa_archive_post`: Archive an article
- `esa_ship_post`: Ship an article (remove WIP)
- `esa_duplicate_post`: Duplicate an article
- `esa_rollback_post_revision`: Roll back to a revision
- `esa_get_comment`: Get a comment
- `esa_create_comment`: Add a comment
- `esa_update_comment`: Edit a comment
- `esa_delete_comment`: Delete a comment
- `esa_get_post_comments`: List comments on a post
- `esa_get_team_comments`: List team comments
- `esa_get_categories`: List categories under a path
- `esa_get_top_categories`: List top-level categories
- `esa_get_all_category_paths`: List all category paths with counts
- `esa_get_attachment`: Fetch an attachment
- `esa_get_search_options_help`: Search syntax help
- `esa_get_markdown_syntax_help`: Markdown syntax help
- `esa_search_help`: Search esa documentation

## FAQ

### What credentials are needed?

An esa access token, supplied as ESA_ACCESS_TOKEN, with read/write or a defined set of read and write scopes.

### How do I run it?

Through docker or npx in your MCP client config, over stdio.

### Is it official?

The registry entry calls it the official MCP server for esa.io.

### Which licence?

MIT.

### Is esa free?

Yes. esa is open source, so you can use and self-host it for free.

### How do I add esa to Claude Code?

Run this command in your terminal: claude mcp add esa --env ESA_ACCESS_TOKEN='<ESA_ACCESS_TOKEN>' -- npx -y @esaio/esa-mcp-server

### What are the best alternatives to esa?

The closest alternatives to esa are Codebase Memory, XERJ, Ha MCP, Claude Code Ultimate Guide and Concord MCP.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ha MCP](https://ai-powered.com/mcp/ha-mcp): Ha MCP is an open-source MCP server for productivity.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.
- [Nautilus Compass Memory](https://ai-powered.com/mcp/nautilus-compass-memory): Nautilus Compass Memory is an open-source MCP server for knowledge and memory.
- [NeuroStack](https://ai-powered.com/mcp/neurostack): NeuroStack is a freemium MCP server for knowledge and memory.
- [note1](https://ai-powered.com/mcp/note1): note1 is an MCP server for productivity.

---
Source: https://ai-powered.com/mcp/esa
