Which integrations are available for this server?

Provides tools for interacting with the Elementary POS public API, enabling management of bills, orders, receipts, stock, items, customers, suppliers, taxes, categories, and webhooks.

How do I use Elementary POS MCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Elementary POS MCP Show me the current actual stock for all items." 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.

Elementary POS MCP

by pedrocastellanos

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

elementary-pos-mcp

Servidor MCP (Model Context Protocol) para la Public API de Elementary POS. Expone facturas, pedidos, recibos, stock, artículos, clientes, proveedores, impuestos, categorías y webhooks como herramientas MCP.

Stack: TypeScript ESM, @modelcontextprotocol/server v2, zod v4, tsx, Node 22.

Arquitectura

src/
  index.ts        # Entry stdio (+ delega a http.ts según MCP_TRANSPORT)
  http.ts         # Transporte Streamable HTTP (stateless), /health, /, /mcp + CORS
  server.ts       # createServer(): registra los 10 módulos de tools
  config.ts       # Validación env con zod, resolución de API key
  lib/
    api-client.ts # Cliente fetch con X-Api-Key, timeout AbortController, errores tipados
    errors.ts     # ElementaryPosApiError / ElementaryPosConfigError
  schemas/        # Validación zod por dominio (bill, order, receipt, stock, item, customer, supplier, webhook, common)
  tools/          # Registro de tools (helpers.ts + 1 fichero por dominio)
examples/
  claude-code/.mcp.json
  cursor/mcp.json
Dockerfile          # Multi-stage Node 22 alpine, usuario no-root, CMD dist/http.js

Flujo: MCP client -> createServer(config) -> register*Tools -> ElementaryPosApiClient -> https://api.elementarypos.com/v1/* con cabecera X-Api-Key.

Autenticación por llamada (prioridad): apiKey param de la tool > header x-api-key / Authorization: Bearer (modo remoto) > env X_API_KEY / ELEMENTARY_POS_API_KEY (modo stdio local).

Related MCP server: MCP Universal EC E-Invoice Server

Herramientas (32)

Dominio	Tool	Tipo	Endpoint Elementary
Bills	`elementary_get_bill`	read	`POST /v1/bill/get-bill`
Bills	`elementary_get_bills`	read	`POST /v1/bill/get-bills`
Categories	`elementary_get_categories`	read	`POST /v1/category/get-categories`
Customers	`elementary_get_customer`	read	`POST /v1/customer/get-customer`
Customers	`elementary_get_customers`	read	`POST /v1/customer/get-customers`
Customers	`elementary_create_customer`	write	`POST /v1/customer/create-customer`
Customers	`elementary_edit_customer`	write/idempotente	`POST /v1/customer/edit-customer`
Customers	`elementary_delete_customer`	write/destructiva	`POST /v1/customer/delete-customer`
Items	`elementary_get_sales_items`	read	`POST /v1/item/get-sales-items`
Items	`elementary_add_sale_item`	write	`POST /v1/item/add-sale-item`
Items	`elementary_edit_sale_item`	write/idempotente	`POST /v1/item/edit-sale-item`
Items	`elementary_delete_sale_item`	write/destructiva	`POST /v1/item/delete-sale-item`
Orders	`elementary_get_order`	read	`POST /v1/order/get-order`
Orders	`elementary_create_order`	write	`POST /v1/order/create-order`
Orders	`elementary_create_orders`	write	`POST /v1/order/create-orders`
Receipts	`elementary_get_receipt`	read	`POST /v1/receipt/get-receipt`
Receipts	`elementary_get_receipts`	read	`POST /v1/receipt/get-receipts`
Receipts	`elementary_get_receipts_get`	read	`GET /v1/receipt/receipts`
Receipts	`elementary_get_receipt_pdf`	stub	Devuelve aviso: API binaria no expuesta en build JSON-only
Stock	`elementary_get_actual_stock`	read	`POST /v1/stock/get-actual-stock-data`
Stock	`elementary_get_stock_changes`	read	`POST /v1/stock/get-stock-changes`
Stock	`elementary_add_stock_change`	write/idempotente	`POST /v1/stock/add-stock-change`
Stock	`elementary_update_stock`	write/idempotente	`POST /v1/stock/update-stock` (máx 100 items)
Suppliers	`elementary_get_supplier`	read	`POST /v1/supplier/get-supplier`
Suppliers	`elementary_get_suppliers`	read	`POST /v1/supplier/get-suppliers`
Suppliers	`elementary_create_supplier`	write	`POST /v1/supplier/create-supplier`
Suppliers	`elementary_edit_supplier`	write/idempotente	`POST /v1/supplier/edit-supplier`
Suppliers	`elementary_delete_supplier`	write/destructiva	`POST /v1/supplier/delete-supplier`
Tax	`elementary_get_tax_settings`	read	`POST /v1/tax/get-tax-settings`
Webhook	`elementary_get_webhook_status`	read	`POST /v1/webhook/get-webhook-status`
Webhook	`elementary_enable_webhook`	write/idempotente	`POST /v1/webhook/enable-webhook`
Webhook	`elementary_disable_webhook`	write/destructiva	`POST /v1/webhook/disable-webhook`

Notas: elementary_create_order crea bill nuevo si se omite billId. En stock, cantidad negativa = venta, positiva = entrada.

Configuración

Variables (src/config.ts, ver .env.example):

Var	Defecto	Descripción
`X_API_KEY` / `ELEMENTARY_POS_API_KEY`	—	Fallback local stdio. En remoto no usar .env, usar header
`ELEMENTARY_POS_BASE_URL`	`https://api.elementarypos.com`	Base API
`ELEMENTARY_POS_TIMEOUT_MS`	`15000`	Timeout fetch
`MCP_TRANSPORT`	`http`	`stdio` \| `http` \| `both`
`MCP_HTTP_PATH`	`/mcp`	Ruta MCP
`PORT` / `HOST`	`3001` / `0.0.0.0`	Servidor HTTP (Docker expone 3001)

Puesta en marcha

pnpm install
pnpm dev            # stdio según MCP_TRANSPORT (tsx src/index.ts)
pnpm dev:http       # HTTP directo (tsx src/http.ts)
pnpm typecheck && pnpm build
pnpm start          # node dist/index.js (stdio)
pnpm start:http     # node dist/http.js (HTTP)

Docker:

docker build -t elementary-pos-mcp .
docker run -p 3001:3001 elementary-pos-mcp
curl http://localhost:3001/health

Endpoints HTTP: GET / (info), GET /health, POST /mcp (protocolo MCP). CORS abierto con x-api-key, mcp-session-id.

Integración clientes

Stdio local (Cursor examples/cursor/mcp.json, Claude Code examples/claude-code/.mcp.json): ajustar /ABSOLUTE/PATH/.../dist/index.js y ELEMENTARY_POS_API_KEY.

Remoto (opencode.json): pasar API key por headers, no por env:

{
  "mcpServers": {
    "elementary-pos": {
      "type": "streamable-http",
      "url": "https://tu-host/mcp",
      "headers": { "x-api-key": "pak-..." }
    }
  }
}

Errores

ElementaryPosApiError incluye status HTTP + payload. Timeout → AbortError con mensaje timed out after {ms}ms. Sin key → error que indica las 3 vías (param, header, env).

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

mcp AOAuth
my.taokeh
Malaysian SME accounting, e-Invoice and payroll for your AI. 64 tools; writes are approved drafts.
ERP Systems Finance
641
CraloOAuth
ai.cralo
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
Agent Orchestration Developer Tools
1
BotFriendly A
xyz.botfriendly
Directory of APIs, merchants, and tools AI agents can actually use.
Search Developer Tools
71
Air Pipe B
io.airpipe
Build, validate, deploy — HTTP APIs, cron jobs, webhooks and MCP tools — from your AI client.
Developer Tools CI/CD & DevOps App Automation
191

Related MCP Servers

KiotViet MCP Server
E-commerce & Retail ERP Systems
haudnn
F
license
Not graded
quality
D
maintenance
Enables AI assistants to manage KiotViet retail and F\&B operations including products, orders, customers, invoices, and inventory through the Public API. Features 36 integrated tools with automatic token refresh, middleware chain support, and configurable presets for different access levels.
Updated 5 months ago (2026-04-11 08:15 UTC)
3
-
MCP Universal EC E-Invoice
Payments & Billing Finance
asgard-ai-platform
A
license
B
quality
D
maintenance
Enables AI agents to issue, void, query, and manage Taiwan e-invoices via 27 MCP tools, wrapping the Universal EC POS Web Service.
Updated 6 months ago (2026-04-03 07:27 UTC)
27
MIT
mcploy
E-commerce & Retail CRM
ogarciabrena
A
license
A
quality
B
maintenance
Exposes the Loyverse API as MCP tools to manage stores, products, inventory, customers, receipts, and more from AI assistants.
Updated 2 months ago (2026-07-08 23:24 UTC)
54
MIT
billz_mcp
E-commerce & Retail ERP Systems
asadbekdev
F
license
C
quality
D
maintenance
MCP server for the BILLZ POS/Retail API 2.0, enabling AI agents to perform analytics and full retail operations including sales, products, customers, reports, and inventory management.
Updated 6 months ago (2026-04-02 13:13 UTC)
18
-