Elementary POS MCP

Servidor MCP en TypeScript para la Elementary POS Public API (api.elementarypos.com, X-Api-Key, endpoints /v1/...). Expone operaciones de lectura/escritura como tools MCP y funciona en stdio (local) y Streamable HTTP (remoto/Docker).

Arquitectura

MCP Client (Cursor / Claude / opencode)
  │  stdio: stdin/stdout  ──► node dist/index.js
  │  http:  POST /mcp      ──► node dist/http.js ──► X-Api-Key ──► Elementary POS API
  └───────────────────────────────► api.elementarypos.com/v1/...

• src/index.ts — stdio (serveStdio)

• src/http.ts — Streamable HTTP stateless (WebStandardStreamableHTTPServerTransport {sessionIdGenerator: undefined}), CORS, /health, /

• src/server.ts — registra 32 tools

• src/config.ts — env + validación zod

• src/lib/api-client.ts — fetch con X-Api-Key, timeout, apiKey por-request

• src/tools/* + src/schemas/*

Related MCP server: MCP Officegest

Herramientas (32)

Write/destructive anotadas con destructiveHint/idempotentHint.

Requisitos

• Node.js 22+ (Docker usa node:22-alpine, pnpm 10.11.0)

• API key de Elementary POS (pak-...)

Variables de entorno

Prioridad API key: apiKey param del tool > header x-api-key (por request) > X_API_KEY env > ELEMENTARY_POS_API_KEY env.

Formas de configurar la API key

1. Remoto Streamable HTTP — header (recomendado Docker)

opencode.json / cliente remoto:

{
  "mcpServers": {
    "elementary-mcp": {
      "type": "remote",
      "url": "http://localhost:3000/mcp",
      "headers": { "x-api-key": "pak-JchAcmiGJgi9Lui41aGIKxfYZRUu9a" }
    }
  }
}

Alternativas: Authorization: "Bearer pak-...". El servidor loguea apiKey from header (pak-JchA...) por request (stateless).

2. Por tool (sin env, multi-tenant)

Cualquier cliente puede pasar apiKey en el input del tool; el LLM lo inyecta si el usuario lo tiene en su config. Útil para mismo despliegue con distintas tiendas:

{ "apiKey": "pak-...", "dateFrom": "2026-08-29", "limit": 100 }

3. Stdio local — env

Para stdio el host inyecta env al proceso:

Cursor .cursor/mcp.json:

{
  "mcpServers": {
    "elementary-pos": {
      "type": "stdio",
      "command": "node",
      "args": ["/ABS/elementary-mcp/dist/index.js"],
      "env": { "X_API_KEY": "${env:X_API_KEY}" }
    }
  }
}

Claude Code:

claude mcp add --transport stdio --env X_API_KEY=pak-... elementary-pos -- node /ABS/dist/index.js

opencode stdio:

{ "type": "local", "command": ["node","dist/index.js"], "environment": { "X_API_KEY": "pak-..." } }

Instalación y build

pnpm install
pnpm run typecheck
pnpm run build
# dev
pnpm run dev              # stdio: tsx src/index.ts (se queda esperando stdin, normal)
pnpm run dev:http         # http: tsx src/http.ts -> http://localhost:3000/mcp
pnpm run start:http       # prod http: node dist/http.js
pnpm run start            # prod stdio: node dist/index.js

Docker

# Dockerfile: node:22-alpine, pnpm 10.11.0, multi-stage, non-root appuser
# EXPOSE 3000, CMD ["node","dist/http.js"]

docker build -t elementary-mcp .
docker run -p 3000:3000 elementary-mcp
# o con puerto custom:
docker run -p 8080:8080 -e PORT=8080 -e MCP_HTTP_PATH=/mcp elementary-mcp
# health
curl http://localhost:3000/health
# MCP endpoint
curl http://localhost:3000/mcp -H "x-api-key: pak-..."

MCP_TRANSPORT=both levanta HTTP + stdio simultáneamente; stdio solo no expone puerto.

API source

Swagger 2.0 api.elementarypos.com.

Desarrollo

pnpm run typecheck
pnpm run build

Logs HTTP: [mcp] POST /mcp apiKey from header o no apiKey header. Got headers: ... para debug de opencode.json.