Minimax MCP server
An MCP server for the Minimax accounting API. It lets Claude and other LLM clients work with a Minimax organisation: look up customers and items, read and create issued and received invoices, orders, stock, journals and the e-document inbox/outbox, and fetch VAT rates, exchange rates and price lists. It supports the Slovenian, Croatian and Serbian Minimax instances.
Built and maintained by Blazium. We also help companies put it into production.
- 37 tools. Every endpoint of the Minimax API is reachable through one of them.
- Two transports. Local
stdiofor Claude Desktop and Claude Code, or streamable HTTP behind a bearer token for a shared server. - Defensive writes. Field names are validated against the Minimax schema before
anything is sent,
RowVersionis handled for you, and a refused login is never retried (Minimax locks the application password after repeated failures).
Contents
- Before you start: Minimax credentials
- Quick start
- Configuration
- Security
- Tools
- Things the Minimax API does not tell you
- Versions and releases
- Development
- Need help with the integration?
Before you start: Minimax credentials
Minimax uses the OAuth2 password grant, which needs two pairs of credentials:
| Variable | Where it comes from |
|---|---|
MINIMAX_CLIENT_ID, MINIMAX_CLIENT_SECRET |
Issued by Minimax support on request, once per integrating application. |
MINIMAX_USERNAME, MINIMAX_PASSWORD |
Not the Minimax login. An application password the user creates on their profile page (login.minimax.si / .hr / .rs) under Gesla za dostop zunanjih aplikacij → Nova aplikacija. |
Repeated failed logins lock that application password, and the user has to delete it and create a new one. So after the token endpoint refuses the credentials once, the server does not try again until it is restarted. If you see an authentication error, fix the credentials and restart; do not loop.
The server acts with the permissions of that Minimax user, in every organisation the user can access. Minimax's own developer guide is at help.minimax.si/help/api-navodila-za-razvijalce.
Quick start
The package is published on PyPI as
minimax-accounting-mcp
(the name minimax-mcp belongs to an unrelated project). It requires Python
3.14; uv downloads it for you if needed.
Claude Desktop (stdio)
Add this to claude_desktop_config.json and restart Claude Desktop:
{
"mcpServers": {
"minimax": {
"command": "uvx",
"args": ["minimax-accounting-mcp"],
"env": {
"MINIMAX_CLIENT_ID": "...",
"MINIMAX_CLIENT_SECRET": "...",
"MINIMAX_USERNAME": "...",
"MINIMAX_PASSWORD": "...",
"MINIMAX_LOCALIZATION": "SI"
}
}
}
}
Pin a version in production use: "args": ["minimax-accounting-mcp==0.1.0"].
Claude Code (stdio)
claude mcp add minimax \
-e MINIMAX_CLIENT_ID=... -e MINIMAX_CLIENT_SECRET=... \
-e MINIMAX_USERNAME=... -e MINIMAX_PASSWORD=... \
-e MINIMAX_LOCALIZATION=SI \
-- uvx minimax-accounting-mcp
Any other MCP client that can launch a stdio server works the same way: the
command is uvx minimax-accounting-mcp and the configuration is the environment.
Your own server (Docker, streamable HTTP)
One container serves one Minimax account to everyone who holds its bearer token. Create an env file:
# minimax.env
MINIMAX_CLIENT_ID=...
MINIMAX_CLIENT_SECRET=...
MINIMAX_USERNAME=...
MINIMAX_PASSWORD=...
MINIMAX_LOCALIZATION=SI
# A long random string, e.g. python -c "import secrets; print(secrets.token_urlsafe(32))"
MINIMAX_MCP_BEARER_TOKEN=...
Run it:
docker run -d --name minimax-mcp --restart unless-stopped \
--env-file minimax.env -p 127.0.0.1:8000:8000 \
ghcr.io/chehcore/minimax-mcp:0.1.0
curl http://127.0.0.1:8000/health # -> ok
The image runs the HTTP transport on 0.0.0.0:8000, serves MCP at /mcp and a
credential-free health check at /health, and has a Docker HEALTHCHECK on it.
Put it behind a reverse proxy that terminates TLS (see Security),
then connect a client:
claude mcp add --transport http minimax https://minimax.example.com/mcp \
--header "Authorization: Bearer <MINIMAX_MCP_BEARER_TOKEN>"
The token is the whole of the authentication. The claude.ai web connector only speaks OAuth, so it cannot use this server directly; Claude Code, Claude Desktop via stdio, and other clients that can send a custom header can.
From source
git clone https://github.com/chehcore/minimax-mcp
cd minimax-mcp
uv sync
uv run minimax-mcp # stdio; set the MINIMAX_* variables first
Configuration
Everything is read from MINIMAX_* environment variables. Empty values count as
unset.
| Variable | Default | |
|---|---|---|
MINIMAX_CLIENT_ID, MINIMAX_CLIENT_SECRET |
— | Required. See credentials. |
MINIMAX_USERNAME, MINIMAX_PASSWORD |
— | Required. The application password, not the Minimax login. |
MINIMAX_LOCALIZATION |
SI |
SI, HR or RS: selects host, path and OAuth scope. |
MINIMAX_ORGANISATION_ID |
— | Used when a tool call omits organisation_id. Without it, such a call fails with an error that points the model to minimax_list_organisations. |
MINIMAX_TRANSPORT |
stdio |
Or streamable-http. The Docker image sets streamable-http. |
MINIMAX_HOST / MINIMAX_PORT |
127.0.0.1 / 8000 |
HTTP transport only. The Docker image sets 0.0.0.0. |
MINIMAX_MCP_BEARER_TOKEN |
— | HTTP transport: required unless bound to loopback. |
MINIMAX_API_BASE_URL / MINIMAX_TOKEN_URL |
derived | Overrides, e.g. for an outbound proxy. |
MINIMAX_TIMEOUT_SECONDS |
30 |
Per request to Minimax. |
MINIMAX_LOG_LEVEL |
INFO |
Logs go to stderr; under stdio, stdout is the protocol channel. |
Missing credentials do not stop the server from starting: the first tool call returns an error naming the variables that are missing.
Security
- Whoever can reach
/mcpacts with the configured Minimax account. Over HTTP every request exceptGET /healthmust carryAuthorization: Bearer <MINIMAX_MCP_BEARER_TOKEN>, compared in constant time. Bound to anything but loopback, the server refuses to start without a token. - Use TLS. The server speaks plain HTTP; put it behind a reverse proxy (nginx, Caddy, Traefik, …) with HTTPS, so the token never crosses the network in clear text.
- Give it its own Minimax user with the narrowest permissions that do the job, and its own application password, so you can revoke it without affecting anyone else.
- The model can write. Create, update, delete and action tools change real accounting data. MCP clients ask before calling a tool by default; keep it that way for write tools unless you know what you are doing.
- One account per process. To serve several Minimax accounts, run several containers, each with its own credentials and token.
Tools
Every API endpoint is reachable through one of the 37 tools, and
tests/test_minimax_registry.py checks that against the Swagger file in both
directions.
- Context:
minimax_get_current_user,minimax_list_organisations,minimax_list_all_organisations,minimax_get_organisation,minimax_get_dashboard. - Generic record tools: these take a
resourcefrom the registry insrc/minimax_mcp/resources.py:minimax_describe_resource,minimax_search_records,minimax_get_record,minimax_create_record,minimax_update_record,minimax_delete_record,minimax_run_action,minimax_list_sync_candidates,minimax_list_attachments,minimax_get_record_pdf,minimax_create_customer_by_tax_number. - Typed lists:
minimax_list_*for issued and received invoices, invoice postings, orders, stock and stock entries, journals and journal entries, the inbox and outbox, postal codes, and contacts by e-mail. - Reference data: VAT rates and accounting types, exchange rates, item settings, item data and price lists, payroll settings.
Try prompts like "List this month's unpaid issued invoices", "Create a customer from tax number SI12345678" or "What is the stock of item X?".
Things the Minimax API does not tell you
What took time to learn, so it does not have to take yours:
- The Swagger file omits every list filter. The query parameters in
tools/lists.pycome from the per-endpoint pages of the API help atmoj.minimax.si/SI/API/Help/Api/GET-api-orgs-organisationId-issuedinvoicesand similar.InvoiceTypeis mandatory on issued invoices. - Minimax ignores unknown JSON fields without saying so, so a misspelt
field drops its value. The write tools check field names against
minimax-swagger.json, which ships inside the package, before sending anything. The file is Minimax's own, as published athttps://moj.minimax.si/SI/API/swagger/docs/v1. - Updates and actions need the record's current
RowVersion. A stale one fails with Concurrency error - record changed by another action (RowVersion).minimax_update_recordreads the record, applies the changes and writes it back. - Creating a record may return an empty body and a
Locationheader. The create tools follow that header, but only on the configured host, because the request carries the bearer token. - Responses never include file contents by default. Generated PDFs and
attachments arrive base64-encoded, so
AttachmentDatais replaced by a size note unless the tool call passesinclude_file_data=true.
Versions and releases
Releases follow Semantic Versioning and are listed in
CHANGELOG.md. Each release vX.Y.Z publishes:
minimax-accounting-mcp==X.Y.Zon PyPI;ghcr.io/chehcore/minimax-mcp:X.Y.Z, plus the moving tags:X.Yand:latest.
Pin X.Y.Z anywhere that matters. A published version is never rebuilt.
Development
uv sync --extra dev
uv run pytest -q
uv run ruff check
To release: bump version in pyproject.toml, add a ## [X.Y.Z] section to
CHANGELOG.md, merge to main, then push the tag vX.Y.Z. The release
workflow refuses a tag that does not match pyproject.toml.
Issues and pull requests are welcome.
Need help with the integration?
This server is free and MIT-licensed, and the instructions above are complete: you can run it yourself. If you would rather not, Blazium does this for a living. We can:
- set up a hosted, secured server for your company or your clients,
- connect Minimax with your other systems (e-invoicing, webshop, CRM, banking),
- build workflows and agents on top of your accounting data,
- adapt the tools to how your team actually works.
Write to info@blazium.si.
Potrebujete pomoč pri uvedbi ali povezavi Minimaxa z drugimi sistemi? Pišite nam na info@blazium.si.
License
MIT. Minimax is a trademark of its owner; this project is not affiliated with or endorsed by Minimax.
Metadata
Release files for minimax-accounting-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| minimax_accounting_mcp-0.1.0.tar.gz | 64.2 kB | With provenance | Details for minimax_accounting_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| minimax_accounting_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for minimax_accounting_mcp-0.1.0-py3-none-any.whl |
Total release size: 127.3 kB
Release files / minimax_accounting_mcp-0.1.0.tar.gz
| Download URL | minimax_accounting_mcp-0.1.0.tar.gz |
|---|---|
| Size | 64.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
beb85f0d54696d79304674475b592df0e8d9a131c819055a934955ed1e4807b5
|
|
BLAKE2b-256 checksum How to use checksums |
4926c5ddc805d2df5cca6d2377bfb9dda6776f70b68aef1bd7f87b3fedd55e3d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / minimax_accounting_mcp-0.1.0-py3-none-any.whl
| Download URL | minimax_accounting_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 63.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
75d05f504ef4e0a9a6c85e5b1ffed9977821dcb15cd053d8805945b5564225f7
|
|
BLAKE2b-256 checksum How to use checksums |
c14320c8ea073927ba8fb05ade3009ac9665135f45e7629a71e6cc6f6f22f19e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for minimax-accounting-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for minimax_accounting_mcp-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.