Qoyod MCP Server

Pequeño servidor MCP (Model Context Protocol) que conecta Claude directamente con el programa de contabilidad قيود (Qoyod) a través de su API REST oficial (https://api.qoyod.com/2.0).

Después de desplegarlo (deploy) en cualquier hosting, obtienes un enlace HTTPS como:

https://your-app.onrender.com/mcp

Añades este enlace como Custom Connector en la configuración de Claude, y Claude podrá leer y crear clientes, facturas, proveedores, asientos de diario y otros recursos de قيود — en cualquier conversación, sin necesidad de abrir el navegador.

1) Herramientas (Tools) disponibles

• qoyod_request — herramienta genérica (passthrough) que cubre cualquier recurso documentado en apidoc.qoyod.com (Accounts, Products, Inventories, Vendors, Purchase Orders, Bills, Customers, Quotes, Invoices, Credit/Debit Notes, Receipts, Journal Entries...).

• Herramientas listas para uso rápido: qoyod_list_customers, qoyod_get_customer, qoyod_create_customer, qoyod_list_products, qoyod_list_invoices, qoyod_get_invoice, qoyod_create_invoice, qoyod_list_bills, qoyod_list_vendors, qoyod_list_journal_entries, qoyod_create_journal_entry, qoyod_list_accounts.

Nota: la documentación general de قيود no menciona todos los campos de cada recurso en detalle. Al crear (create_*), verifica la forma correcta del payload a través de apidoc.qoyod.com o prueba primero con qoyod_request con datos de prueba.

Related MCP server: Piriod MCP Server

2) Ejecución local (opcional, para probar antes del despliegue)

Requiere Node.js 18 o superior.

npm install
cp .env.example .env
# افتح .env وضع مفتاح الـ API الخاص بك من قيود (Settings > General Settings > API Key)
npm start

El servidor funcionará en http://localhost:3000/mcp.

3) Despliegue (Deploy) en un hosting gratuito — ejemplo con Render.com

1. Crea una cuenta gratuita en render.com (o usa tu cuenta de GitHub para iniciar sesión).

2. Sube esta carpeta a un nuevo repositorio de GitHub (puedes crear un repositorio vacío en github.com y luego subir los archivos desde la interfaz web directamente si no estás familiarizado con git).

3. Desde el panel de Render: New + → Web Service → elige el repositorio.

4. Configuración:

   • Build Command: npm install

   • Start Command: npm start

   • Environment Variable: añade QOYOD_API_KEY y su valor es la clave de API de قيود.

5. Pulsa Deploy. Cuando termine la compilación, obtendrás un enlace como: https://qoyod-mcp-server.onrender.com

6. El enlace MCP completo que usarás en Claude es: https://qoyod-mcp-server.onrender.com/mcp

Otras alternativas

Los mismos pasos se aplican aproximadamente a Railway, Fly.io y Cloudflare Workers (requiere un pequeño ajuste para ser compatible con el entorno de Workers).

Nota sobre el plan gratuito de Render: el servidor se "duerme" tras un período de inactividad y necesita ~30-50 segundos para la primera solicitud después de la inactividad. Si quieres una respuesta inmediata siempre, necesitas un plan de pago u otro hosting que no suspenda el servicio.

4) Conectarlo a Claude

1. En la configuración de Claude, busca la sección Connectors (conectores) → Add custom connector.

2. Pega el enlace: https://your-app.onrender.com/mcp

3. Guarda. Después aparecerán las herramientas de قيود entre las herramientas disponibles de Claude en cualquier conversación en la que actives este conector.

5) Seguridad

• Tu clave de API se almacena solo como variable de entorno (QOYOD_API_KEY) en tu hosting — no aparece en el código ni se envía a ningún otro tercero.

• No compartas tu enlace /mcp con nadie en quien no confíes; da acceso completo a la cuenta de قيود asociada (según los permisos de la clave).

• Si sospechas que la clave se ha filtrado, ve a قيود → Configuración general → pulsa Generate New Key para emitir una nueva clave que invalida la anterior inmediatamente.