Oblio.eu accounting MCP Server (Unofficial)

MCP Server for the Oblio API, enabling Claude and other MCP-compatible platforms to interact with Oblio.eu accounting software.

Create invoices, manage documents, collect payments, query nomenclatures, and submit e-Factura to Romania's SPV system -- all through natural language.

Prerequisites

• Node.js >= 24 with npm >= 11.14 (bundled with Node.js 24.18+)
• Docker (optional)
• An active Oblio.eu account with API access

Setup

1. Get your Oblio API credentials

• Log in at oblio.eu
• Go to Setari > Date Cont
• Copy your email and API secret
• Note your company CIF (e.g. RO37311090)

2. Add to your Claude Desktop config

Environment variables are passed through the MCP client configuration:

Add to your Claude Desktop config or other MCP-compatible AI tool (claude_desktop_config.json):

Using npx (coming soon)

Once the package is published to npm, no installation will be required:

{
  "mcpServers": {
    "oblio": {
      "command": "npx",
      "args": ["-y", "oblio-mcp"],
      "env": {
        "OBLIO_API_EMAIL": "your-email@example.com",
        "OBLIO_API_SECRET": "your-api-secret",
        "CIF": "your-company-cif"
      }
    }
  }
}

Using a local clone (recommended)

git clone https://github.com/valentinludu/oblio-mcp.git
cd oblio-mcp
npm install

Then add to your config:

{
  "mcpServers": {
    "oblio": {
      "command": "node",
      "args": ["/path/to/oblio-mcp/dist/index.js"],
      "env": {
        "OBLIO_API_EMAIL": "your-email@example.com",
        "OBLIO_API_SECRET": "your-api-secret",
        "CIF": "your-company-cif"
      }
    }
  }
}

Using Docker

docker build -t oblio-mcp .

{
  "mcpServers": {
    "oblio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OBLIO_API_EMAIL",
        "-e",
        "OBLIO_API_SECRET",
        "-e",
        "CIF",
        "oblio-mcp"
      ],
      "env": {
        "OBLIO_API_EMAIL": "your-email@example.com",
        "OBLIO_API_SECRET": "your-api-secret",
        "CIF": "your-company-cif"
      }
    }
  }
}

Environment Variables

Required

| Variable | Description | | ------------------ | ------------------------------ | | OBLIO_API_EMAIL | Your Oblio account email | | OBLIO_API_SECRET | API secret from Oblio settings |

Optional

| Variable | Description | Default | | ------------- | --------------------------------------- | ------- | | CIF | Company CIF (can also be set via API) | None | | LOG_LEVEL | Logging level: error, warn, info, debug | info | | API_TIMEOUT | API request timeout in milliseconds | 30000 | | PORT | Server port for future HTTP transport | None |

Tools

Document Management

| Tool | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | create_document | Creates an invoice (factura), proforma, or delivery notice (aviz). Requires client details, at least one product, a series name, and issue date. Returns the created document's series, number, and link. | | get_document | Retrieves a single document by type, series name, and number. Returns document details, link, and payment history. | | list_documents | Lists and filters documents with pagination. Supports filtering by series, date range, client, draft/cancelled/collected status. Returns up to 100 results per page. | | delete_document | Permanently deletes a document. Only the last document in a series can be deleted. Optionally removes the associated payment. | | cancel_document | Cancels (annuls) a document, marking it as void. The document remains in the system. | | restore_document | Restores a previously cancelled document, making it active again. |

Payments

| Tool | Description | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | collect_payment | Records a payment against an existing invoice. Supports payment types: Chitanta, Bon fiscal, Ordin de plata, Card, CEC, and others. Defaults to the full invoice amount if value is omitted. |

Nomenclatures (Reference Data)

| Tool | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | get_nomenclatures | Fetches reference data from Oblio. Types: companies, clients, products, vat_rates, series, languages, management. Results are paginated (max 250 per page). |

e-Factura (SPV)

| Tool | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | create_einvoice | Submits an existing invoice to Romania's SPV system for e-Factura. Returns status code: 0=processing, 1=success, 2=errors, -1=not sent. | | get_einvoice_archive | Downloads the e-Invoice archive (XML) from SPV for a previously submitted invoice. |

Configuration

| Tool | Description | | --------- | ------------------------------------------------------------------- | | set_cif | Sets the company CIF (tax ID) used for all subsequent API requests. | | get_cif | Returns the currently configured company CIF. |

Prompts

The server includes 28 prompt templates for common operations: creating documents, retrieving documents, cancelling/restoring/deleting documents, searching nomenclatures, collecting payments, listing invoices, and managing e-Factura submissions.

Troubleshooting

If you encounter issues:

1. Verify your Oblio account is active and has API access
2. Check that OBLIO_API_EMAIL and OBLIO_API_SECRET are correctly set
3. Ensure your company CIF is set (via CIF env var or the set_cif tool)
4. Confirm you have the necessary permissions for the operations you're performing
5. For debugging, set LOG_LEVEL=debug in your MCP client configuration

License

ISC