Ephemr MCP server

Give Claude, Codex, Cursor, Zed, or any MCP-aware client direct access to your Ephemr account. Once configured, the model can publish pages, manage aliases, and inspect event history without you writing any HTTP glue code.

Install

Homebrew (macOS, Linux) — recommended. Handles upgrades and sidesteps macOS Gatekeeper entirely:

brew install veturu/ephemr/ephemr-mcp

Install script — detects your OS/arch, places the binary on $PATH, and strips the macOS quarantine attribute:

curl -sSf https://ephemr.io/install-mcp.sh | sh

Pinned versions

If you need a specific version or a stable URL for a container image, binaries for every release live at github.com/veturu/homebrew-ephemr/releases. The install script above pulls the same files. Once installed, put ephemr-mcp on $PATH — MCP hosts don't resolve shell aliases, so the binary itself has to be discoverable.

Create an API key

Go to /portal/keys in the portal and create a key. You'll see the full secret exactly once — copy it into the env var below.

Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add:

{
  "mcpServers": {
    "ephemr": {
      "command": "ephemr-mcp",
      "env": {
        "EPHEMR_API_KEY": "eph_live_...",
        "EPHEMR_API_BASE": "https://ephemr.io"
      }
    }
  }
}

Restart Claude Desktop. The Ephemr tools will appear in the tool picker.

Configure Claude Code

The fastest way is the built-in command (writes to your project's .claude/settings.json or user-scoped config):

claude mcp add ephemr --env EPHEMR_API_KEY=eph_live_... --env EPHEMR_API_BASE=https://ephemr.io -- ephemr-mcp

Or add it manually to ~/.claude/settings.json:

{
  "mcpServers": {
    "ephemr": {
      "command": "ephemr-mcp",
      "env": {
        "EPHEMR_API_KEY": "eph_live_...",
        "EPHEMR_API_BASE": "https://ephemr.io"
      }
    }
  }
}

List servers with claude mcp list; verify the tools appear in a new session.

Configure Codex CLI

Codex uses ~/.codex/config.toml for MCP configuration. Add an mcp_servers entry like this:

[mcp_servers.ephemr]
command = "ephemr-mcp"
env = { EPHEMR_API_KEY = "eph_live_...", EPHEMR_API_BASE = "https://ephemr.io" }

Then restart Codex CLI, or add the server from the terminal with:

codex mcp add ephemr --env EPHEMR_API_KEY=eph_live_... --env EPHEMR_API_BASE=https://ephemr.io -- ephemr-mcp

Once configured, the Ephemr tools show up alongside your other MCP tools in Codex.

Configure Codex Desktop

Codex Desktop uses the same MCP configuration model as Codex CLI. Open Codex settings and edit config.toml, or update ~/.codex/config.toml directly with the same block:

[mcp_servers.ephemr]
command = "ephemr-mcp"
env = { EPHEMR_API_KEY = "eph_live_...", EPHEMR_API_BASE = "https://ephemr.io" }

After saving, restart Codex Desktop. The Ephemr MCP tools should appear automatically.

Tools exposed

Tool	What it does
`publish_page`	Publish a local `.zip` archive and return the shareable URL. Optionally attaches to an alias and replaces the previous target.
`list_pages`	List every page on the account (active, expired, deleted).
`delete_page`	Delete a page by id.
`get_page_events`	Return the lifecycle event timeline for a page.
`list_aliases`	List stable aliases owned by the account.
`create_alias`	Claim a new alias name (3–32 chars, `[a-z0-9-]`).
`delete_alias`	Delete an alias. The current target page remains reachable at its slug URL.

Example prompts

Once configured, prompts like these work end-to-end:

"Zip the files in ~/demo and publish to Ephemr under the alias demo. Replace the previous version."
"List my active Ephemr pages and their expiry times."
"Show me the event history for page {id}."
"Create an alias called status and publish ~/report.zip to it."

Troubleshooting

Tools don't appear in Claude Desktop, Claude Code, or Codex: confirm ephemr-mcp is on $PATH — MCP clients don't resolve shell aliases. Run which ephemr-mcp. For Claude Code, also try claude mcp list to confirm the entry is registered.
401 unauthorized: regenerate an API key at /portal/keys. Raw keys are shown once; you can't recover an old one.
macOS silently refuses to launch it: Gatekeeper quarantine on a hand-downloaded binary. Reinstall via brew install veturu/ephemr/ephemr-mcp or the install script — both sidestep it.
Logs: the server writes errors to stderr. Claude Desktop captures this in its MCP logs; Codex exposes MCP/server errors through its normal client logs and MCP status views.

The MCP server is a thin wrapper over the public API at /api/v1. If you'd rather script directly, the API works identically with curl or any HTTP client.