# contasimple-mcp

Servidor [MCP](https://modelcontextprotocol.io) para [Contasimple](https://www.contasimple.com). Permite a Claude (u otro cliente MCP) consultar y registrar facturas, proveedores y pagos usando la [API v2 de Contasimple](https://api.contasimple.com/swagger/ui/index).

## Requisitos

- Node.js 18 o superior
- Una clave de API de Contasimple, generada desde la configuración de tu cuenta

## Configuración

El servidor se ejecuta con `npx`, no hace falta clonar ni instalar nada. La clave se pasa por la variable de entorno `CONTASIMPLE_API_KEY`.

### Claude Code

```bash
claude mcp add contasimple -e CONTASIMPLE_API_KEY=tu_clave -- npx -y contasimple-mcp
```

Con escritura activada:

```bash
claude mcp add contasimple -e CONTASIMPLE_API_KEY=tu_clave -e CONTASIMPLE_ALLOW_WRITE=1 -- npx -y contasimple-mcp
```

### Claude Desktop

Edita `claude_desktop_config.json` (Ajustes → Desarrollador → Editar configuración):

```json
{
  "mcpServers": {
    "contasimple": {
      "command": "npx",
      "args": ["-y", "contasimple-mcp"],
      "env": {
        "CONTASIMPLE_API_KEY": "tu_clave",
        "CONTASIMPLE_ALLOW_WRITE": "0"
      }
    }
  }
}
```

### Cursor y otros clientes

Cualquier cliente MCP por stdio sirve con la misma configuración: comando `npx`, argumentos `-y contasimple-mcp` y las variables de entorno.

### Varias cuentas

Añade una entrada por cuenta de Contasimple, cada una con su clave:

```json
{
  "mcpServers": {
    "contasimple-empresa-a": {
      "command": "npx",
      "args": ["-y", "contasimple-mcp"],
      "env": { "CONTASIMPLE_API_KEY": "clave_a" }
    },
    "contasimple-empresa-b": {
      "command": "npx",
      "args": ["-y", "contasimple-mcp"],
      "env": { "CONTASIMPLE_API_KEY": "clave_b" }
    }
  }
}
```

## Variables de entorno

| Variable | Obligatoria | Descripción |
| --- | --- | --- |
| `CONTASIMPLE_API_KEY` | Sí | Clave de API de Contasimple |
| `CONTASIMPLE_ALLOW_WRITE` | No | `1` para permitir crear proveedores, facturas, pagos y adjuntos. Por defecto solo lectura |

## Herramientas

### Lectura

| Tool | Descripción |
| --- | --- |
| `cs_whoami` | Usuario y empresa activa, y si la escritura está permitida |
| `cs_list_periods` | Periodos contables (trimestres) y su estado |
| `cs_list_invoices` | Facturas emitidas o recibidas de un trimestre, con filtros |
| `cs_get_invoice` | Detalle completo de una factura |
| `cs_search_invoice_by_number` | Busca facturas por número en todos los periodos |
| `cs_pending_summary` | Pendientes de cobro o pago de un mes |
| `cs_search_entities` | Busca proveedores o clientes por nombre o NIF |
| `cs_list_invoice_classes` | Clases de gasto/ingreso válidas |
| `cs_list_payment_methods` | Formas de pago configuradas |
| `cs_list_payments` | Pagos o cobros de una factura |
| `cs_download_invoice_pdf` | Descarga el PDF de una factura a una ruta local |

### Escritura (requiere `CONTASIMPLE_ALLOW_WRITE=1`)

| Tool | Descripción |
| --- | --- |
| `cs_create_provider` | Crea un proveedor |
| `cs_create_received_invoice` | Registra una factura recibida calculando IVA y bases |
| `cs_attach_file` | Adjunta un PDF o imagen local a una factura |
| `cs_add_payment` | Registra un pago o cobro (por defecto, todo lo pendiente) |
| `cs_delete_payment` | Elimina un pago registrado por error |

## Desarrollo

```bash
npm install
npm run build
npm run lint
```

Para probarlo en local sin publicar:

```bash
claude mcp add contasimple-dev -e CONTASIMPLE_API_KEY=tu_clave -- node /ruta/a/contasimple-mcp/dist/index.js
```

O con el inspector de MCP:

```bash
CONTASIMPLE_API_KEY=tu_clave npx @modelcontextprotocol/inspector node dist/index.js
```

## Publicación

```bash
npm login
npm publish
```

`prepublishOnly` ejecuta lint y build antes de publicar; el paquete solo incluye `dist/`, `README.md` y `LICENSE`.

## Licencia

[MIT](LICENSE)