Importar diario y libros de IVA — book_imports MCP

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.

When to use

Use book_imports for delete, import, upload. Use book_imports_read for the companion actions. The live tool list determines availability.

Input

{
  "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.

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.

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "description": "The import's id from list.",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

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.

{
  "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"
}

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.

{
  "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.

Ask for an upload link

{
  "action": "upload",
  "filename": "diario-2025.csv",
  "content_type": "text/csv",
  "size_bytes": 254310
}

Save it whole

{
  "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.

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

Connect

Clients

Use

Reference

Tools

Importar diario y libros de IVA — book_imports MCP

When to use

Input

Actions

Import actions

Output

Example

​When to use

​Input

​Actions

​Import actions

​Output

​Example

When to use

Input

Actions

Import actions

Output

Example