Metadata-Version: 2.4
Name: minimax-accounting-mcp
Version: 0.1.0
Summary: MCP server for the Minimax accounting API (moj.minimax.si / .hr / .rs): invoices, customers, items, stock, journals and more, for LLM clients.
Author-email: Blazium <info@blazium.si>
License-Expression: MIT
Project-URL: Homepage, https://github.com/chehcore/minimax-mcp
Project-URL: Issues, https://github.com/chehcore/minimax-mcp/issues
Project-URL: Changelog, https://github.com/chehcore/minimax-mcp/blob/main/CHANGELOG.md
Project-URL: Blazium, https://blazium.si
Keywords: mcp,model-context-protocol,minimax,accounting,erp,invoicing,slovenia,croatia,serbia,claude
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pydantic-settings>=2.3.0
Requires-Dist: uvicorn>=0.30.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: ruff==0.14.5; extra == "dev"
Dynamic: license-file

# 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. Minimax's own developer guide is at
[help.minimax.si/help/api-navodila-za-razvijalce](https://help.minimax.si/help/api-navodila-za-razvijalce).

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