Skip to main content

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 stdio for 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, RowVersion is handled for you, and a refused login is never retried (Minimax locks the application password after repeated failures).

Contents

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 /mcp acts with the configured Minimax account. Over HTTP every request except GET /health must carry Authorization: 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 resource from the registry in src/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.py come from the per-endpoint pages of the API help at moj.minimax.si/SI/API/Help/Api/GET-api-orgs-organisationId-issuedinvoices and similar. InvoiceType is 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 at https://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_record reads the record, applies the changes and writes it back.
  • Creating a record may return an empty body and a Location header. 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 AttachmentData is replaced by a size note unless the tool call passes include_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.Z on PyPI;
  • ghcr.io/chehcore/minimax-mcp:X.Y.Z, plus the moving tags :X.Y and :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)

Source distribution for minimax-accounting-mcp 0.1.0
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)

Table of built distributions (wheels) for minimax-accounting-mcp 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page