Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-esa-server-python list the 10 most recent articles"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
esa.io API と連携するための Model Context Protocol Server (mcp server)です。Pythonで実装しています。
現在は以下の機能を提供しています。
ユーザー情報取得（user_get_info）
記事一覧取得（posts_get_list）
記事詳細取得（posts_get_detail）
記事作成 (posts_create)
記事更新 (posts_update)
記事削除 (posts_delete)
Related MCP server: Qiita MCP Server
esa.ioのAPIトークンを発行済であること
uv が使えること
インターネット接続
esa.ioのAPIトークンの発行方法
あなたの esa.io チームのページにアクセスします (例: https://<your-team-name>.esa.io/)。
左カラムのSETTINGSをクリックし、「ユーザー設定」>「外部アプリ連携」を選択します。
「Personal access tokens」セクションで、「Generate new token」をクリックします。
トークン名 (例: mcp-server) を入力し、必要な権限スコープを選択します。この MCP サーバーには少なくとも以下の権限が必要です:
read (記事の読み取り)
write (記事の作成・更新・削除)
read_user (ユーザー情報の取得) （この項目は自動的に有効になるため、表示されない可能性があります）
「Save」をクリックします。
表示されたトークンを必ずコピーして安全な場所に保管してください。このトークンは一度しか表示されません。
コピーしたトークンは、後述の .env ファイルの ESA_TOKEN の値として貼り付けます。
esa.io では、サインアップから2ヶ月間の無料トライアル期間が提供されています。この期間を利用して、テスト用のチーム名とAPIトークンを取得することができます。
セキュリティのため、トークンは直接公開しないようご注意ください。
uv sync開発に参加する場合や、MCPInspectorを利用する場合は、以下の手順で環境を構築します。
環境変数の設定
.env.example を参考にして、.env をサーバーを実行したいディレクトリ(.env.exampleと同じ場所)を作成します。
ESA_TEAM_NAME="YOUR_ESA_TEAM_NAME" # Replace with your esa.io team name (e.g., "myteam")
ESA_TOKEN="YOUR_ESA_API_TOKEN" # Replace with your esa.io API access token実行方法 下記コマンドを実行後に、指示のあるURLからブラウザを開くことで、MCP Inspectorを使って、各コマンド(記事作成など)を実行することができます。
uv run mcp run main.pymcp.jsonの作成例
プロジェクトルートまたは ~/.cursor/mcp.json に以下のような設定ファイルを用意します。
{
"mcpServers": {
"mcp-esa-server": {
"command": "uv",
"args": [
"--directory",
"<プロジェクトの絶対パス>",
"run",
"main.py"
],
"env": {
"ESA_TEAM_NAME": "<your-team-name>",
"ESA_TOKEN": "<your-esa-token>"
}
}
}
}<your-team-name> と <your-esa-token> は各自のesa.ioチーム名・APIトークンに置き換えてください。
env: 環境変数を 直接 設定します。この方法を使用する場合、.cursor/mcp.json のコミットは絶対に避けてください。
CursorエディタでMCPサーバーを起動
CursorエディタのコマンドパレットやUIから「MCPサーバーを起動」または「AIツールを有効化」します。
mcp.jsonの設定に従い、uv run main.py でサーバーが起動します。
.env ファイルや環境変数も自動的に読み込まれます。
AIチャットやツールパネルからAPIを呼び出し
AIチャット上で user_get_info や posts_get_list などのMCPツールを呼び出すことで、esa.io APIと連携した操作が可能です。
mcp-esa-serverを使って記事の作成をお願いします などとチャット上で書き込むことで利用できます。
このプロジェクトは MIT License の下で公開されています。
このプロジェクトの一部では、以下のMIT Licenseで公開されているコードを参照しています。
esa-mcp-server
GitHubリポジトリ: [https://github.com/masseater/esa-mcp-server]
ライセンス: MIT License
generated by Cursor (gemini-2.5-pro-exp-03-25)
Create a new post on esa.io
Args: name: Post title body_md: Post body in Markdown format tags: List of tags for the post category: Category path (e.g., 'foo/bar') wip: Whether the post is Work In Progress (default: true) message: Commit message for the post
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| body_md | Yes | ||
| tags | No | List of tags for the post | |
| category | No | Category path (e.g., 'foo/bar') | |
| wip | No | Whether the post is Work In Progress (default: true) | |
| message | No | Commit message for the post |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While 'Create a new post' implies a write/mutation operation, the description doesn't address critical behavioral aspects: required permissions, whether the post is immediately published (vs. draft), rate limits, error conditions, or what happens on success. The parameter documentation in the Args section provides some operational context but doesn't cover broader behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized but not optimally structured. The opening sentence is clear and front-loaded, but the Args section uses a documentation-style format rather than integrated prose. While all information is relevant, the structure could be more cohesive. The description avoids redundancy but doesn't achieve the efficiency of the highest-scoring examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a mutation tool with no annotations and no output schema, the description provides adequate but incomplete context. The parameter documentation is strong, but missing behavioral information about permissions, publishing workflow, and expected responses leaves gaps. For a post-creation tool, the description should ideally address whether the post becomes immediately visible, what authentication is required, and what the tool returns upon success.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant value beyond the input schema through the detailed Args section. While schema description coverage is 67%, the description provides clear explanations for all 6 parameters, including default values (e.g., 'wip: default: true'), format examples ('category path (e.g., 'foo/bar')'), and purpose clarifications. This compensates well for the schema coverage gap and provides practical guidance for parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new post') and target resource ('on esa.io'), which is specific and unambiguous. It distinguishes this tool from siblings like posts_delete, posts_get_detail, and posts_update by focusing on creation rather than deletion, retrieval, or modification. However, it doesn't explicitly differentiate from other potential creation tools beyond the esa.io context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, appropriate contexts, or when other tools like posts_update might be more suitable. The agent must infer usage from the tool name and sibling names alone, with no explicit direction provided in the description text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a post on esa.io
Args: post_number: The number of the post to delete
| Name | Required | Description | Default |
|---|---|---|---|
| post_number | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Delete') but doesn't mention critical traits like whether deletion is permanent, requires specific permissions, has side effects (e.g., affecting linked content), or what the response looks like (e.g., success/failure). This leaves significant gaps for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, with the core action stated first ('Delete a post on esa.io') followed by parameter details in a structured 'Args:' section. There's minimal waste, though the formatting could be slightly more polished.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a destructive operation with no annotations, no output schema, and low schema coverage, the description is incomplete. It lacks details on behavioral traits (e.g., permanence, permissions), usage context, and expected outcomes, making it inadequate for safe and effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning by explaining that 'post_number' identifies 'The number of the post to delete,' which clarifies the parameter's role beyond the schema's title ('Post Number'). However, it doesn't provide additional context like format examples or constraints, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Delete') and resource ('a post on esa.io'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like posts_update (which might also modify posts) or mention that deletion is permanent versus other operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like posts_update for modifications or posts_get_detail for viewing. The description lacks context about prerequisites (e.g., needing proper permissions) or exclusions (e.g., not for bulk deletion).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific post from esa.io
Args: post_number: The number of the post to retrieve
| Name | Required | Description | Default |
|---|---|---|---|
| post_number | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a read operation ('Get details'), but doesn't mention authentication requirements, rate limits, error conditions, or what format/details are returned. For a read tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise with two sentences. The first states the purpose clearly, and the second documents the single parameter. There's no unnecessary verbiage, though the structure could be improved by integrating parameter information more naturally.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read operation with no annotations, no output schema, and 0% schema description coverage, the description is incomplete. It doesn't explain what details are returned, error handling, authentication needs, or how this differs from the list-retrieval sibling tool. The agent lacks sufficient context for reliable usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only repeats the parameter name ('post_number') without explaining what constitutes a valid post number, where to find it, or its format/range. This adds minimal value beyond the schema's basic type declaration.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get details') and resource ('a specific post from esa.io'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'posts_get_list' which retrieves multiple posts versus this tool's single-post focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There's no mention of when to choose this over 'posts_get_list' for single-post retrieval, nor any prerequisites or context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a list of posts from esa.io
Args: q: Search query page: Page number per_page: Number of posts per page (max 100)
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| page | No | ||
| per_page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a 'Get' operation which implies read-only behavior, but doesn't mention authentication requirements, rate limits, error conditions, or what format the returned list will have. The description mentions 'max 100' for per_page which is useful behavioral context, but otherwise lacks critical information about how this tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with a clear purpose statement followed by parameter explanations. The structure with 'Args:' section is helpful. However, the parameter explanations could be more front-loaded with the purpose statement, and some information like the max constraint could be integrated more smoothly rather than as a parenthetical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read operation with 3 parameters and no output schema, the description provides basic functionality but lacks important context. It doesn't explain the return format, error handling, authentication needs, or how pagination works beyond mentioning page numbers. The 0% schema description coverage means the description should do more to compensate, but it only partially succeeds.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides basic semantics for all three parameters: 'q' as search query, 'page' as page number, and 'per_page' as number of posts per page with max constraint. However, it doesn't explain query syntax, default values (all parameters are optional with null defaults), or what happens when parameters are omitted. The description adds meaningful context but doesn't fully compensate for the complete lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a list of posts from esa.io' which specifies the verb ('Get'), resource ('posts'), and source ('esa.io'). It distinguishes from siblings like posts_get_detail (list vs detail) and posts_create/update/delete (read vs write operations), though it doesn't explicitly mention these distinctions in the description text itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like posts_get_detail for individual posts or user_get_info for user data. There's no context about when to use search vs. browse functionality or any prerequisites for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing post on esa.io
Args: post_number: The number of the post to update name: New post title body_md: New post body in Markdown format tags: New list of tags category: New category path wip: New WIP status message: Commit message for the update
| Name | Required | Description | Default |
|---|---|---|---|
| post_number | Yes | ||
| name | No | New post title | |
| body_md | No | New post body in Markdown format | |
| tags | No | New list of tags | |
| category | No | New category path | |
| wip | No | New WIP status | |
| message | No | Commit message for the update |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states this is an update operation but doesn't disclose behavioral traits like whether it requires authentication, what permissions are needed, if it's idempotent, what happens on partial updates, or error conditions. The description only lists parameters without behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the purpose in the first sentence, followed by a structured parameter list. However, the parameter explanations are somewhat redundant with the schema descriptions, and there's no wasted text, though it could be more efficient by omitting parameter details already in the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool with 7 parameters, no annotations, and no output schema, the description is incomplete. It lacks critical context such as authentication requirements, error handling, what the update returns (e.g., success confirmation or updated post data), and how it interacts with sibling tools. The high parameter coverage doesn't compensate for missing behavioral and output information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (86%), with all parameters except post_number having descriptions in the schema. The description adds minimal value beyond the schema—it repeats parameter names and brief explanations but doesn't provide additional semantics like format examples (e.g., category path syntax) or constraints. Baseline 3 is appropriate given the schema does most of the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing post on esa.io' which specifies the verb (update), resource (post), and platform (esa.io). It distinguishes from siblings like posts_create (create) and posts_delete (delete), though it doesn't explicitly differentiate from posts_get_detail or posts_get_list beyond the update action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. While the description implies it's for updating existing posts (vs. creating new ones with posts_create), there's no explicit mention of prerequisites, when-not-to-use scenarios, or how it relates to other tools like posts_get_detail for retrieving posts before updating.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current esa.io user information
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states 'Get' which implies a read operation, but doesn't disclose any behavioral traits such as authentication requirements, rate limits, error conditions, or what specific user information is returned. This leaves significant gaps in understanding how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any unnecessary words. It is appropriately sized and front-loaded, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what user information is returned (e.g., name, email, permissions), nor does it cover behavioral aspects like authentication or errors. For a tool with no structured data to rely on, the description should provide more context to be fully helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and the schema description coverage is 100% (though trivial since there are no parameters). The description doesn't need to add parameter semantics, so a baseline score of 4 is appropriate as it doesn't introduce confusion or redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'current esa.io user information', making the purpose specific and understandable. However, it doesn't differentiate from sibling tools (which are all post-related), but since this tool operates on a different resource (user vs posts), the lack of explicit differentiation is less critical.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context, or exclusions, leaving the agent to infer usage based solely on the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0posts_createposts_deleteposts_get_detailposts_get_listposts_updateuser_get_infoEvery tool has a clearly distinct purpose with no ambiguity. The five post-related tools cover different CRUD operations (create, delete, get_detail, get_list, update), and the user_get_info tool handles a completely separate user information domain. An agent can easily distinguish between these tools based on their names and descriptions.
All tools follow a consistent verb_noun pattern with perfect uniformity. Post-related tools use 'posts_' prefix followed by action verbs (create, delete, get_detail, get_list, update), and the user tool follows the same structure with 'user_get_info'. There are no deviations in naming conventions throughout the set.
Six tools is well-scoped and appropriate for this esa.io content management server. The set provides complete CRUD operations for posts plus user information retrieval, with each tool earning its place. This is neither too sparse nor bloated for the domain of managing posts and user data on esa.io.
The tool surface provides complete coverage for the esa.io post management domain with full CRUD operations (create, read, update, delete) plus listing/search functionality. The addition of user information retrieval rounds out the surface nicely. There are no obvious gaps or dead ends for agents working with posts on esa.io.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
MCP server for accessing curated awesome list documentation
A basic MCP server to operate on the Postman API.
A MCP server built for developers enabling Git based project management with project and personal…
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/scnsh/mcp-esa-server-python'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
