esa

You can run the esa MCP Server locally to access and manage your esa.io data through a programmable API. It provides read/write access to posts, tags, and comments via a configurable MCP connection, so you can build integrations, automations, or dashboards that stay in sync with your esa team.

How to use

Set up the server to connect to your esa.io team, then point your MCP client at it. Use the npx-based or Docker-based configurations to run the server locally, and switch to read-only mode if you only need to fetch data. The server exposes tools to list and retrieve posts, tags, and comments, enabling you to read and monitor content without altering your esa.io workspace.

How to install

Prerequisites: You need Node.js (for npx) or Docker installed on your machine. You also require a personal access token from your esa.io team.

1. Generate a personal access token in your esa.io team settings under Applications.

2. Prepare a configuration for your MCP client using one of the options below.

Configuration via npx

{
  "mcpServers": {
    "esa": {
      "command": "npx",
      "args": [
        "-y",
        "@koki-develop/esa-mcp-server@latest"
      ],
      "env": {
        "ESA_TEAM": "<your-team-name>",
        "ESA_ACCESS_TOKEN": "<your-personal-access-token>"
      }
    }
  }
}

Configuration via Docker

{
  "mcpServers": {
    "esa": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ESA_TEAM",
        "-e",
        "ESA_ACCESS_TOKEN",
        "ghcr.io/koki-develop/esa-mcp-server:latest"
      ],
      "env": {
        "ESA_TEAM": "<your-team-name>",
        "ESA_ACCESS_TOKEN": "<your-personal-access-token>"
      }
    }
  }
}

Read-only Mode

To enable read-only mode that only allows read operations, add the --readonly flag to the startup command. In read-only mode, you can get posts, a specific post, tags, and post comments, but you cannot create, update, or delete data.

{
  "mcpServers": {
    "esa": {
      "command": "npx",
      "args": [
        "-y",
        "@koki-develop/esa-mcp-server@latest",
        "--readonly"
      ],
      "env": {
        "ESA_TEAM": "<your-team-name>",
        "ESA_ACCESS_TOKEN": "<your-personal-access-token>"
      }
    }
  }
}

Read-only Mode via Docker

{
  "mcpServers": {
    "esa": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ESA_TEAM",
        "-e",
        "ESA_ACCESS_TOKEN",
        "ghcr.io/koki-develop/esa-mcp-server:latest",
        "--readonly"
      ],
      "env": {
        "ESA_TEAM": "<your-team-name>",
        "ESA_ACCESS_TOKEN": "<your-personal-access-token>"
      }
    }
  }
}

Security and tokens

Keep your ESA team name and access token secure. Do not share the token or commit it into source control. Use read-only mode for environments where write access is not required.

Notes

The server is designed to provide a programmable interface to esa.io data. It supports standard MCP operations for posts, tags, and comments and can be run either with npx or in a Docker container.

Available tools

get_posts

Retrieve a list of posts from the esa team with support for search, filtering, sorting, and pagination.

get_post

Retrieve a specific post by post number with full details and engagement metrics.

create_post

Create a new post in the esa team with a title and optional content, tags, and metadata.

update_post

Update an existing post by post number with new content, tags, or metadata.

delete_post

Delete an existing post permanently by post number.

get_tags

Get a list of all tags used in the esa team with post counts.

get_post_comments

Retrieve comments for a specific post with pagination.

create_post_comment

Create a new comment on a post with Markdown content.

update_comment

Update an existing comment by its ID with new content.

delete_comment

Delete an existing comment by its ID.