> ## Documentation Index
> Fetch the complete documentation index at: https://docs.melso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Melso MCP: https://mcp.melso.ai/mcp (OAuth; one company per connection). Documentation-search MCP: https://docs.melso.ai/mcp; it does not act on customer accounts.
>
> Use the live tool list and respect company membership. Ask the person to approve the exact invoice or tax return version in the signed-in app. Melso's professionals prepare and file included returns after approval; an AI assistant does not file. A prepared file or an approval is not evidence of filing: only the AEAT's reference and receipt are. Keep credentials out of chat and logs.

# Importar diario y libros de IVA — book_imports MCP

> MCP book_imports: upload and import books, or delete an unposted VAT-book import. Live for an empresa.

Import the books a company kept in another accounting program (ContaPlus, A3, Sage...) from the person's files, sent in the Melso chat (attachment\_id) or uploaded from another client with upload (upload\_id), as the program exports them: its libro diario (book journal), its VAT books (book issued: facturas expedidas, saved as income; book received: facturas recibidas, saved as expenses), which the 303, 390, 347 and 349 then count, and its list of subaccounts (book subaccounts: each one's name and NIF), which names the books' subaccounts. read shows what a file holds and what keeps it from being saved; import saves it whole or not at all. Import journals oldest first: a year's opening then reopens the year before's books. list shows the imports, opening balances included; delete can remove an unposted VAT book, but posted journals and opening balances stay immutable and require explicit reversals in the app. A refused file is never fixed by hand: the person exports it again. Books with no journal to import open with accounting opening\_balance. Each action accepts only its own fields (\* required): import(book\*, attachment\_id, upload\_id); upload(filename\*, content\_type\*, size\_bytes\*); delete(id\*).

**Availability:** Empresa.

**Access:** Live for an empresa, in the app and over MCP when the connection lists `book_imports`. Journal and VAT-book REST imports are private beta. Posted journals cannot be deleted here. Correct them with reversals in the app.

The live tool list is authoritative: the company's plan and your role can narrow this contract. [Understand access](https://docs.melso.ai/mcp/permissions.md).

## When to use

Use `book_imports` for `delete`, `import`, `upload`. Use [`book_imports_read`](https://docs.melso.ai/mcp/tools/book-imports-read) for the companion actions. The live tool list determines availability.

## Input

```json theme={null}
{
  "additionalProperties": false,
  "oneOf": [
    {
      "additionalProperties": false,
      "properties": {
        "action": {
          "const": "import"
        },
        "attachment_id": {
          "description": "In the Melso chat: the attachment_id of the file (CSV, TXT or Excel as the accounting program exports it) the person sent, at most 10 MB.",
          "type": "string"
        },
        "book": {
          "description": "journal: the libro diario. issued: the libro de facturas expedidas (sales, saved as income). received: the libro de facturas recibidas (purchases, saved as expenses). subaccounts: the list of subaccounts (subcuentas, plan de cuentas) with each one's name and NIF.",
          "enum": [
            "journal",
            "issued",
            "received",
            "subaccounts"
          ],
          "type": "string"
        },
        "upload_id": {
          "description": "From another client: the upload_id from upload, once the file (CSV, TXT or Excel as the accounting program exports it) was PUT to its upload_url.",
          "type": "string"
        }
      },
      "required": [
        "action",
        "book"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "action": {
          "const": "upload"
        },
        "content_type": {
          "description": "The file's type: text/plain (Norma 43, TXT), text/csv, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/pdf or application/octet-stream.",
          "type": "string"
        },
        "filename": {
          "description": "The file's name, such as extracto.n43 or diario.xlsx.",
          "type": "string"
        },
        "size_bytes": {
          "description": "The file's exact size in bytes.",
          "minimum": 1,
          "type": "integer"
        }
      },
      "required": [
        "action",
        "filename",
        "content_type",
        "size_bytes"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "action": {
          "const": "delete"
        },
        "id": {
          "description": "The import's id from list.",
          "type": "string"
        }
      },
      "required": [
        "action",
        "id"
      ],
      "type": "object"
    }
  ],
  "properties": {
    "action": {
      "enum": [
        "import",
        "upload",
        "delete"
      ],
      "type": "string"
    },
    "attachment_id": {
      "description": "In the Melso chat: the attachment_id of the file (CSV, TXT or Excel as the accounting program exports it) the person sent, at most 10 MB.",
      "type": "string"
    },
    "book": {
      "description": "journal: the libro diario. issued: the libro de facturas expedidas (sales, saved as income). received: the libro de facturas recibidas (purchases, saved as expenses). subaccounts: the list of subaccounts (subcuentas, plan de cuentas) with each one's name and NIF.",
      "enum": [
        "journal",
        "issued",
        "received",
        "subaccounts"
      ],
      "type": "string"
    },
    "content_type": {
      "description": "The file's type: text/plain (Norma 43, TXT), text/csv, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/pdf or application/octet-stream.",
      "type": "string"
    },
    "filename": {
      "description": "The file's name, such as extracto.n43 or diario.xlsx.",
      "type": "string"
    },
    "id": {
      "description": "The import's id from list.",
      "type": "string"
    },
    "size_bytes": {
      "description": "The file's exact size in bytes.",
      "minimum": 1,
      "type": "integer"
    },
    "upload_id": {
      "description": "From another client: the upload_id from upload, once the file (CSV, TXT or Excel as the accounting program exports it) was PUT to its upload_url.",
      "type": "string"
    }
  },
  "required": [
    "action"
  ],
  "type": "object"
}
```

## Actions

The tool's schema combines the fields of every action. Each action accepts only its own fields below; send `action` with them.

### Import actions

`upload` returns a link, `import` saves a file whole or not at all and `delete` removes an unposted VAT book. They need a plan with the tools. Posted journals stay immutable.

> [accordion] delete
>
> Delete an unposted VAT book by its id from list, removing its imported income or expenses. Posted journals remain immutable and return posted\_journal\_immutable; correct them with reversal entries in the web app. A VAT book is refused (period\_filed) while a 303 that counts its invoices is approved or filed. Only when the person asks for it.
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "id": {
>       "description": "The import's id from list.",
>       "type": "string"
>     }
>   },
>   "required": [
>     "id"
>   ],
>   "type": "object"
> }
> ```

> [accordion] import
>
> Save a journal, VAT book or list of subaccounts the person gave, whole or not at all. A journal's entries become the company's books up to its last day; a VAT book's new invoices become income (issued) or expenses (received), leaving out those already in Melso; a list of subaccounts names each one it gives, and sets its tax ID when the list has one, keeping the company's other subaccounts. A refusal names its code (already\_imported, overlaps\_import, later\_import, opening\_differs, future\_entries, nothing\_new, or the row of an unreadable or unbalanced file): explain it to the person and never retry with a file you edited.
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "attachment_id": {
>       "description": "In the Melso chat: the attachment_id of the file (CSV, TXT or Excel as the accounting program exports it) the person sent, at most 10 MB.",
>       "type": "string"
>     },
>     "book": {
>       "description": "journal: the libro diario. issued: the libro de facturas expedidas (sales, saved as income). received: the libro de facturas recibidas (purchases, saved as expenses). subaccounts: the list of subaccounts (subcuentas, plan de cuentas) with each one's name and NIF.",
>       "enum": [
>         "journal",
>         "issued",
>         "received",
>         "subaccounts"
>       ],
>       "type": "string"
>     },
>     "upload_id": {
>       "description": "From another client: the upload_id from upload, once the file (CSV, TXT or Excel as the accounting program exports it) was PUT to its upload_url.",
>       "type": "string"
>     }
>   },
>   "required": [
>     "book"
>   ],
>   "type": "object"
> }
> ```

> [accordion] upload
>
> Get a link to upload the journal, VAT book or list of subaccounts as the accounting program exports it (at most 10 MB) when you can run commands: PUT the file to upload\_url, then call read and then import with book with upload\_id. Without a shell, give the person web\_upload\_url to upload it in Contabilidad instead.
>
> ```json theme={null}
> {
>   "additionalProperties": false,
>   "properties": {
>     "content_type": {
>       "description": "The file's type: text/plain (Norma 43, TXT), text/csv, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/pdf or application/octet-stream.",
>       "type": "string"
>     },
>     "filename": {
>       "description": "The file's name, such as extracto.n43 or diario.xlsx.",
>       "type": "string"
>     },
>     "size_bytes": {
>       "description": "The file's exact size in bytes.",
>       "minimum": 1,
>       "type": "integer"
>     }
>   },
>   "required": [
>     "filename",
>     "content_type",
>     "size_bytes"
>   ],
>   "type": "object"
> }
> ```

## Output

`upload` returns an upload link and its `upload_id`. `import` saves the file whole or refuses it with a code. `delete` removes an unposted VAT book; posted journals stay immutable.

The result uses MCP `content` blocks; JSON payloads are encoded in text and may also appear in `structuredContent`. Check `isError` before reading a success payload. When the server declares an `outputSchema`, it is reproduced below. Check the action result and its declared fields before reporting success.

## Example

Use the actions of this tool in the order shown; its companion tool covers the other actions. These are the `arguments` of each call, in order.

**1. Ask for an upload link**

```json theme={null}
{
  "action": "upload",
  "filename": "diario-2025.csv",
  "content_type": "text/csv",
  "size_bytes": 254310
}
```

**2. Save it whole**

```json theme={null}
{
  "action": "import",
  "book": "journal",
  "upload_id": "11111111-1111-4111-8111-111111111111"
}
```

The first call as a request. Use an OAuth access token issued for this MCP resource and replace the example identifiers with values from your own company. Write actions change data.

```bash theme={null}
curl --fail-with-body https://mcp.melso.ai/mcp \
  -H "Authorization: Bearer $MELSO_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data-binary @- <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "book_imports",
    "arguments": {
      "action": "upload",
      "filename": "diario-2025.csv",
      "content_type": "text/csv",
      "size_bytes": 254310
    }
  }
}
JSON
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.