@ryanseaotter/mcp-server

MCP server for SeaOtter-hosted Hermes Agent. Use your agent from Claude, Cursor, or Codex without leaving chat.

SEAOTTER_API_KEY is a SeaOtter access key (so_…) — the same value used as Authorization: Bearer so_… for /api/v1. It is not the per-agent Hermes runtime credential (api_server_key); the MCP server fetches that after authenticating.

Setup guide (source of truth): docs.seaotter.dev/mcp

Quick install

# Claude Code
claude mcp add seaotter --env SEAOTTER_API_KEY=so_… -- npx -y @ryanseaotter/mcp-server

# Codex
codex mcp add seaotter --env SEAOTTER_API_KEY=so_… -- npx -y @ryanseaotter/mcp-server

Cursor — .cursor/mcp.json:

{
  "mcpServers": {
    "seaotter": {
      "command": "npx",
      "args": ["-y", "@ryanseaotter/mcp-server"],
      "env": { "SEAOTTER_API_KEY": "so_…" }
    }
  }
}

Develop

npm install
npm test
npm run build
npm run dev   # stdio

See DEPENDENCIES.md for backend vs client ship matrix.

Publish (maintainers)

Releases are published to npm as @ryanseaotter/mcp-server via GitHub Actions.

1. Bump "version" in package.json (and commit).
2. Tag and push: git tag mcp-server-v0.1.0 && git push origin mcp-server-v0.1.0
3. Workflow mcp-server-publish.yml runs npm ci + npm publish (prepublishOnly builds and tests).

Requires repo secret NPM_TOKEN (granular npm token with publish access for @ryanseaotter/mcp-server).