Minimax MCP Server
# Minimax MCP server
An [MCP](https://modelcontextprotocol.io) server for the
[Minimax](https://www.minimax.si) 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](https://blazium.si). We also
[help companies put it into production](#need-help-with-the-integration).
- **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](#before-you-start-minimax-credentials)
- [Quick start](#quick-start)
- [Configuration](#configuration)
- [Security](#security)
- [Tools](#tools)
- [Things the Minimax API does not tell you](#things-the-minimax-api-does-not-tell-you)
- [Versions and releases](#versions-and-releases)
- [Development](#development)
- [Need help with the integration?](#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.
## Quick start
The package is published on PyPI as
[`minimax-accounting-mcp`](https://pypi.org/project/minimax-accounting-mcp/)
(the name `minimax-mcp` belongs to an unrelated project). It requires Python
3.14; [`uv`](https://docs.astral.sh/uv/) downloads it for you if needed.
### Claude Desktop (stdio)
Add this to `claude_desktop_config.json` and restart Claude Desktop:
```json
{
"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)
```sh
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:
```sh
# 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:
```sh
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](#security)),
then connect a client:
```sh
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
```sh
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](#before-you-start-minimax-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](https://semver.org) and are listed in
[CHANGELOG.md](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
```sh
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](https://blazium.si)
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](mailto:info@blazium.si)**.
*Potrebujete pomoč pri uvedbi ali povezavi Minimaxa z drugimi sistemi? Pišite
nam na [info@blazium.si](mailto:info@blazium.si).*
## License
[MIT](LICENSE). Minimax is a trademark of its owner; this project is not
affiliated with or endorsed by Minimax.
TDQS
Scored across 37 tools
Most tools target clearly distinct resources or actions, and descriptions explicitly cross-reference each other (e.g. stock vs. stock entries vs. item stock). A few pairs overlap enough to invite misselection: list_organisations vs. list_all_organisations, list_journals vs. list_journals_vod_standard, and create_record vs. create_customer_by_tax_number. The guidance notes help, but an agent still has to read descriptions carefully to pick correctly.
Every tool carries the minimax_ prefix followed by a consistent snake_case verb_noun pattern (list_*, get_*, create_*, update_*, delete_*, search_*, find_*, run_action). Variants like list_all_organisations and list_journals_vod_standard still follow the pattern coherently. No camelCase or ad-hoc naming appears.
At 37 tools the surface is heavy for a single MCP server and exceeds the 25-tool threshold, requiring the agent to navigate many similar list_* tools. While an ERP domain plausibly justifies breadth, several listing tools could be consolidated (e.g. the organisation and stock list variants). The count is a cognitive burden rather than a well-scoped set.
Coverage is broad: full record CRUD, dedicated list tools for invoices/orders/journals/stock/inbox, business actions, attachments, PDFs, VAT rates, exchange rates, and payroll settings. Minor gaps exist, such as no explicit attach/upload tool or payroll data operations, but core workflows are covered end to end.