esa

This MCP server exposes esa.io as MCP tools, allowing you to search, read, create, update, and delete esa articles through a standardized Model Context Protocol interface. The server is configured to run via npx and provides tools such as search_esa_posts, read_esa_post, read_esa_multiple_posts, create_esa_post, update_esa_post, and delete_esa_post. After starting the server, you can issue MCP-style requests to perform actions against your esa workspace using the provided tool names. The included environment variables (ESA_API_KEY and DEFAULT_ESA_TEAM) ensure that the server can authenticate with esa.io and know which team to operate on by default. You can customise these tools and their queries via the MCP payloads, enabling precise article retrieval, creation, and management without exposing raw ESA endpoints to clients.

Prerequisites:

• Node.js (recommended LTS version) installed on your machine
• npm or yarn available
• Access to an esa.io API key and knowledge of your default team

Installation steps:

1. Install Node.js from https://nodejs.org if you don’t have it.
2. Open a terminal and navigate to your project directory.
3. Install the MCP server package via npx (per the README configuration you’ll use):

# Example: you’ll run this in your MCP config or as a startup step
npx -y esa-mcp-server@latest

4. Export or configure the required environment variables as shown in the mcp_config (ESA_API_KEY and DEFAULT_ESA_TEAM).
5. Start the MCP server and verify it’s listening on the expected port (default is typically 8000 or as configured by the server).

If you prefer a local install path, you can also install the package globally or via npm install and run the server script as appropriate for your environment.

Tips and considerations:

• Ensure your ESA API key has the necessary permissions for the actions you plan to perform (read, create, update, delete).
• The server configuration prefers a default ESA team via DEFAULT_ESA_TEAM; override per request payload if needed.
• If you encounter authentication errors, double-check the API key scope and that the key is correctly passed to the server’s environment.
• The tooling names to call via MCP are: search_esa_posts, read_esa_post, read_esa_multiple_posts, create_esa_post, update_esa_post, delete_esa_post, and get_search_query_document (for complex queries).
• Review the server’s src/server.ts for implementation details and any rate-limit considerations with the esa.io API.
• When deploying, consider using a modular approach (as suggested in the repository notes) if you plan to scale or lazy-load features to manage context length.