SimpleERP MCP server
Commit Oct 22, 2026Manages quoting, workforce, and intervention planning for home-care agencies through a centralized ERP system.
Also known as gpbcom/simpe-erp
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 22, 2026
- License
- MIT
What is SimpleERP MCP?
SimpleERP manages quoting, workforce, and intervention planning for home-care agencies through a centralized ERP system.
Summary generated from the project's README
About SimpleERP MCP server
Managing quotes, workforce schedules, and intervention planning for home-care agencies is what simpe-erp enables. This system centralizes the entire workflow, from an assistant writing a quote to a manager approving prices and the subsequent generation of weekly visit schedules that account for travel time and breaks. It provides specialized interfaces for assistants to view their specific calendars and customers, while administrators can manage the entire workforce, validate quotes, and view planned interventions on a map.
The system runs locally using Docker and Docker Compose, requiring approximately 5 GB of free memory to handle the planning solver and message broker. It utilizes a complex architecture involving PostgreSQL for data, MinIO for photographs, and RabbitMQ for event processing. Developers can deploy the full stack, including an observability chain with Grafana and Prometheus, to monitor the health and metrics of the API and background workers.
What you can do with it
- 1Generate weekly care schedulesAn AI client could request the creation of a weekly visit plan that accounts for travel time and lunch breaks.
- 2Validate pending service quotesA manager can use the system to review and approve quotes submitted by assistants.
- 3Visualize intervention locationsUsers can view a geographic map of all planned visits with assistant photographs and customer names.
- 4Manage workforce qualificationsAdministrators can search the workforce and update the specific qualifications of employees.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
COMPOSE_FILE
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablegpbcom/simpe-erp is public and reachablegithub.com/gpbcom/simpe-erp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-22github.com/gpbcom/simpe-erp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubWhat it does
An agency quotes a family for care at home, a manager approves the price, and
the accepted work becomes a week of visits — who goes where, in what order, with
travel time and a lunch break accounted for. SimpleERP runs all three of those,
and the workforce and customer records behind them.
For a home-care assistant
- Their own record: contact details and address they may change; contract type and qualifications shown but locked, because those are a manager's decision.
- Their week as a calendar, computed from the accepted quotes.
- The customers they serve — not the agency's whole book.
- Quotes they have written, and a button that submits one for validation.
For a manager or administrator
- Every quote, with a validation queue: an assistant's submission waits here until somebody who sets prices agrees to it.
- The workforce, searchable, with the qualification editor.
- A map of every planned intervention over a configurable window, each pin being the assistant's photograph, each tooltip naming the customer.
- A notification centre, fed over the broker and pushed live over SSE.
Overall architecture
Four application processes and three stores. The API, both workers and the migrator run the same image with different entry points — one image built four ways cannot drift the way four Dockerfiles do.
┌──────────────┐
browser ────────▶ │ React SPA │ ─────────┐
└──────────────┘ │ REST + SSE
▼
┌────────────────┐ ┌──────────────┐ ┌────────┐
│ worker │ ◀────▶ │ RabbitMQ │◀─│ API │
│ · planning │ events └──────────────┘ └────────┘
│ · notifications│ │
└────────────────┘ │
│ │
└──────────▶ PostgreSQL ◀──────────────────┘
MinIO (photographs)
| Process | Does |
|---|---|
| migrate | Runs Alembic to head, once, and exits. Everything else waits for it |
| api | Serves HTTP and holds the SSE connections |
| worker-planning | Consumes planning-runs: runs the CP-SAT solves |
| worker-notifications | Consumes quote-notifications: writes notifications, sends email |
| frontend | Vite dev server, or nginx serving a built bundle and proxying /api |
Inside the backend
A uv workspace of six members with a strict, one-directional dependency graph.
Nothing points back up it.
models ← storage ← service ← api
↑
├── worker
└── seed
models holds the domain and configuration and imports nothing first-party.
storage owns the tables, mappers and repositories — and never commits, because
the session it is handed already belongs to a transaction. service holds the
business logic and raises its own MT* exceptions rather than HTTP ones. api
translates those exceptions to statuses, once, and its endpoints contain no
business logic.
The worker deliberately does not depend on api: a background consumer that
pulled in FastAPI to read one YAML file would make the graph a ring.
Two flows worth knowing
A request passes CORS → authentication → transaction → router → service → repository. The order is load-bearing at both ends: CORS outermost so a rejected credential still carries its headers, and the transaction innermost so it commits before the response is written.
An event is published by the API and consumed by the worker. A publish that fails never fails the request that caused it — a quote is submitted whether or not the broker was reachable, because the manager's queue is a database query rather than a message.
Requirements
To run it, nothing but a container runtime:
| Docker Engine | 24 or newer |
| Docker Compose | v2 (docker compose, not docker-compose) |
| Memory | ~5 GB free — the solver and the broker are the hungry parts, and the observability chain adds about a gigabyte |
| Ports | 5173, 8000, 5432, 5672, 15672, 9000, 9001, 1025, 8025, 9101, 9102, and 3000, 3101, 9090, 4317, 4318 for observability |
The development overlay publishes every one of those ports so you can reach the
database and the broker directly. If something already holds one, either stop it
or drop that mapping from infra/compose/docker-compose.dev.yaml.
To work on the code, a toolchain per language — none of it needed if you only run the stack:
| Backend | Python 3.14 and uv |
uv sync installs the rest |
| Front-end | Node 20 | .nvmrc pins it; npm ci installs the rest |
| GUI campaign | Python 3.9+ and Playwright browsers | pip install -r qa/requirements.txt && rfbrowser init |
The pinned versions live in backend/.python-version and frontend/.nvmrc, and
CI reads both from those files rather than repeating them.
Outbound network is needed in two places, and only two. Nominatim is called when an address is geocoded — which happens during model validation, so it fires when a customer or an assistant is created, and never when one is read. The seeder supplies coordinates precisely so it does not call it forty times. The other is the image and package registries, at build time.
Getting it running
cp infra/compose/.env.example infra/compose/.env
make up-build
make is the short way in: the compose files live under infra/compose/, so
every raw command needs two -f flags, and the Makefile at the root passes
both for you. Spelled out, that first command is:
docker compose -f infra/compose/docker-compose.yaml -f infra/compose/docker-compose.dev.yaml up --build
That brings up PostgreSQL, MinIO, RabbitMQ, the API, both workers, Mailpit, the
Vite dev server and the whole observability chain, runs the migrations once
through the migrate service, and seeds a working agency — 12 assistants,
40 customers, a service catalog and 54 quotes spread across every status.
Wait for Bucket simple-erp is ready. and the seeder's credential block. The first
build takes a few minutes, and afterwards a start is seconds.
| Application | http://localhost:5173 |
| API and its docs | http://localhost:8000 · http://localhost:8000/docs · http://localhost:8000/redoc |
| Caught email | http://localhost:8025 |
| Broker management | http://localhost:15672 — simple_erp / simple_erp_dev |
| Object store console | http://localhost:9001 — simple_erp_dev / simple_erp_dev_secret |
Observability
Every process serves the same three probes, on the same three paths. /health
answers whether it is alive, /ready whether it can reach what it needs, and
/metrics a Prometheus exposition. A worker that is up but cannot reach the
broker answers 200 on the first and 503 on the second, which is the whole
reason there are two.
| Process | Liveness | Readiness | Metrics |
|---|---|---|---|
| API | http://localhost:8000/health | http://localhost:8000/ready | http://localhost:8000/metrics |
| Planning worker | http://localhost:9101/health | http://localhost:9101/ready | http://localhost:9101/metrics |
| Notification worker | http://localhost:9102/health | http://localhost:9102/ready | http://localhost:9102/metrics |
The dashboards behind them come up with everything else — the development stack always runs the full observability chain, so a panel that has rotted is something you find on a Tuesday rather than the day you needed it. It costs five more containers and roughly a gigabyte of memory, which is the deliberate trade.
| Grafana | http://localhost:3000 — no sign-in, anonymous admin · http://localhost:3000/explore to query the logs |
| Prometheus | http://localhost:9090 · targets · rules · alerts |
| Loki | http://localhost:3101/ready · http://localhost:3101/metrics — an API, not a UI; read the logs in Grafana. Published on 3101 because the RobotCode editor extension holds 3100 |
| OTLP ingest | localhost:4317 (gRPC) · localhost:4318 (HTTP) — endpoints the collector accepts spans on, not pages |
Loki is published for curl, not for a browser — it serves an API and no
interface of its own, and logs are read in Grafana. What the port buys is the
one question Grafana cannot answer. An empty Explore pane looks identical
whether Alloy is shipping nothing, Loki is refusing it, or the query is simply
wrong; /ready and /metrics separate those in one request each.
Tempo and Alloy still publish nothing, on purpose. Grafana reaches Tempo over the compose network, and Alloy scrapes the container runtime's own logs rather than serving anything — so a port for either would be another way to look at data Grafana already shows, and another thing to remember is running.
The Prometheus targets page is the one to open first when a panel is empty — an exporter that is down there explains a blank dashboard faster than the dashboard does. → docs/14
Sign in with any of the seeded accounts, all sharing the password
simple-erp-demo-2026:
| Role | Address | Lands on |
|---|---|---|
| Administrator | admin@simple-erp.fr |
The quote screen |
| Manager, runs the seeded team | manager@simple-erp.fr |
The quote screen |
| Manager, runs no team | manager2@simple-erp.fr |
The quote screen |
| Manager, on the rounds | marc.dubois@simple-erp.fr |
The quote screen |
| Assistant | luc.martin@simple-erp.fr |
Their own planning |
Every seeded assistant signs in as firstname.lastname@simple-erp.fr.
The seeded company operates from two sites — Siège Paris, its head office,
and Antenne Lyon, a branch that holds nobody — and every seeded person and
quote belongs to one team, Equipe principale, run by manager@simple-erp.fr.
Sign in as manager2@simple-erp.fr to see the other side of that: they run no
team, so their quote book, workforce and household list are all empty while the
administrator's are full. That is the team narrowing, not a broken screen.
Marc Dubois is a manager who still covers rounds — they hold both a manager's role and an assistant record. Sign in as them to see the employment section of My account in its editable form, where the contract type, the qualifications and whether this person goes out on rounds can be changed. The same section renders locked for Luc Martin, who holds the assistant role.
Docker
Three compose files. The base is never run alone — it describes what the application is, and an overlay says how you want to run it.
| File | Adds |
|---|---|
infra/compose/docker-compose.yaml |
The services themselves: postgres, minio, minio-init, rabbitmq, migrate, backend, worker-planning, worker-notifications, frontend — plus pgbouncer behind a pooled profile, which an ordinary up does not start |
infra/compose/docker-compose.dev.yaml |
Source bind-mounts, live reload, every port published, Mailpit, the seeder, and the whole observability chain — Prometheus, Loki, Tempo, Grafana, Alloy and the OpenTelemetry Collector |
infra/compose/docker-compose.prod.yaml |
Restart policies, per-role resource limits and replicas, nginx, mandatory secrets |
pgbouncer is off by default because it is there to be exercised rather than
needed: asyncpg caches server-side prepared statements per connection, and
under transaction pooling a "connection" is a different backend from one
transaction to the next. The engine passes statement_cache_size=0
unconditionally to prevent that, and --profile pooled is what proves the
setting still works. → docs/13
Observability is part of the dev overlay rather than an overlay of its own —
see Observability above for the addresses. It reads the
same alert rules the Helm chart ships (infra/chart/rules/), so an alert
cannot fire on a laptop and not in the cluster.
→ docs/14
Because two -f flags on every command gets tedious, there are two ways round
it. Either use the Makefile at the root, which passes both on every target:
make # list the targets
make up # start, in the background
make stop # stop, keeping the containers and the data
make down # stop and remove the containers, keeping the data
…or export the pair once per shell and use docker compose directly:
export COMPOSE_FILE=infra/compose/docker-compose.yaml:infra/compose/docker-compose.dev.yaml
Whichever you pick, use the same two files to go down as you did to come up.
mailpit, seed and the whole observability chain are declared only in the
dev overlay, so a bare docker compose down leaves them running attached to a
network it has just deleted — and the next up fails with
network <id> not found, naming the network rather than the containers that are
really the problem. The Makefile exists mostly to make that unreachable.
Every raw command below assumes COMPOSE_FILE is exported. Without it, spell
both files out.
Day to day
make |
docker compose |
|
|---|---|---|
make up |
docker compose up -d |
start, in the background |
make up-build |
docker compose up -d --build |
rebuild first — after a dependency change |
make ps |
docker compose ps |
what is running, and is it healthy |
make logs S=backend |
docker compose logs -f backend |
follow one service |
| — | docker compose logs -f backend worker-planning |
…or several |
make stop |
docker compose stop |
stop, keeping the data |
make down |
docker compose down --remove-orphans |
stop and remove the containers |
make seed |
docker compose run --rm seed |
re-run the seeder |
make clean |
docker compose down -v && … up --build |
destroys the data — see Starting over |
make urls |
— | print every address the stack publishes |
make replan-config |
docker compose restart worker-planning |
pick up an edited backend/conf/app.dev.yaml |
make replan-config is worth knowing about because backend/conf/ is
bind-mounted: the solver settings can be changed and tried without a rebuild,
and the planning worker only reads them at start.
Application source is bind-mounted in development: editing a .py reloads
uvicorn, editing a .tsx hot-reloads Vite. You only need --build when a
dependency changes — pyproject.toml, uv.lock, package.json — or when the
Dockerfile does.
Starting a slice of it
The dependency graph is declared, so naming one service starts what it needs:
docker compose up -d backend # …and postgres, minio, rabbitmq
docker compose up -d frontend # …and the whole chain behind it
docker compose up -d postgres rabbitmq # the stores alone, to run the app on the host
Running things inside the stack
docker compose exec backend alembic -c conf/alembic.ini current
docker compose exec backend alembic -c conf/alembic.ini upgrade head
docker compose exec backend bash # a shell in the API container
docker compose exec postgres psql -U simple_erp simple_erp # a database prompt
docker compose run --rm seed # re-run the seeder (idempotent)
The seeder writes nothing on a second run — every identifier is derived from a natural key, so it upserts. Running it again is always safe.
The test suite is not among these, and cannot be: the runtime image carries
no uv and no test framework, and backend/.dockerignore keeps tests/ out of
the build context entirely. That is deliberate — the image that runs the suite
would be the image that reaches production. The suite is hermetic, so it needs
none of this stack anyway: run it on the host, which is also what CI does.
cd backend && uv run pytest
Starting over
make clean # both steps below, with both -f flags
or, spelled out:
DEV="-f infra/compose/docker-compose.yaml -f infra/compose/docker-compose.dev.yaml"
docker compose $DEV down -v --remove-orphans # containers AND volumes: a clean database
docker compose $DEV up --build # rebuild and reseed from nothing
-v destroys postgres-data, minio-data and rabbitmq-data. In development
that is the fastest way back to a known state. Anywhere else it is data loss.
make clean is the same thing and just as destructive — it is not a cache
sweep.
Use the same -f files to go down as you did to come up, which is the one
thing the Makefile guarantees. mailpit and seed are defined only in the
dev overlay, so a bare docker compose down leaves them behind attached to the
network it has just deleted — and the next up fails with
network <id> not found, naming the network rather than the two containers that
are really the problem.
Rebuilding one image
docker compose build backend # the API, both workers and the migrator share this image
docker compose build --no-cache frontend
docker compose up -d --force-recreate backend
The worker runs the same image as the API with a different entry point, so
build backend rebuilds both. That is deliberate: one image built two ways
cannot drift the way two Dockerfiles do.
When something will not start
docker compose ps # look for unhealthy or exited
docker compose logs backend | tail -50
docker compose logs minio-init # bucket creation — photographs and map pins
docker compose logs seed # the credential block prints here
| Symptom | Usually |
|---|---|
backend restarts in a loop |
Migrations could not run — read its logs; check POSTGRES_PASSWORD matches |
| Photographs and map pins are broken | minio-init did not complete; re-run docker compose up minio-init |
| No notifications arrive | worker-notifications is down, or RabbitMQ never went healthy — it takes ~20 s on a cold start |
| Login rejects the seeded accounts | The seeder did not run: docker compose run --rm seed |
| A port is already in use | Something else holds 5432, 8000 or 5173; stop it, or drop that port from the dev overlay |
network <id> not found on up |
A previous down used a different -f set — see Starting over |
password authentication failed for user "simple_erp" |
A volume from before the rename — see below |
After the compose files moved into infra/compose
The base file declares name: rt-erp, so the project name — and every volume
name with it — is unchanged by the move. If you have removed that line, or you
run compose from somewhere that does not pick the base file up, the project is
named after the directory instead and the stack comes up against three empty
volumes.
That does not look like an empty database. The stores bake their credentials in when they first initialise an empty volume, so what you get is the authentication failure below — naming the right user, which reads exactly like a typo in the configuration.
docker volume ls | grep rt-erp_ # postgres-data, minio-data, rabbitmq-data
If those exist and the stack is not using them, the data is fine and the project
name is wrong. Put name: rt-erp back.
Note also that .env now belongs beside the compose files, in
infra/compose/. Compose reads it from the project directory, which is the
directory of the first -f file; one left at the repository root is silently
not read, and the stack comes up on the development defaults without saying so.
Upgrading a stack created before the SimpleERP rename
The application was called rt-erp, and its database user, broker user and
bucket were named after it. If your volumes were created before the rename, the
first thing you will see is:
asyncpg.exceptions.InvalidPasswordError: password authentication failed for user "simple_erp"
POSTGRES_USER, RABBITMQ_DEFAULT_USER and MINIO_ROOT_USER are read only
when the store initialises itself. Changing them in compose does nothing to a
volume that already exists — the database still holds rt_erp while the
application now connects as simple_erp. Postgres fails first because the
backend reaches it first. The broker and the object store would fail next.
For a development stack, throw the volumes away — the data is seeded, and reseeding takes seconds:
docker compose -f infra/compose/docker-compose.yaml -f infra/compose/docker-compose.dev.yaml down -v --remove-orphans
docker network rm rt-erp_rt-erp # the network named after the old product
docker compose -f infra/compose/docker-compose.yaml -f infra/compose/docker-compose.dev.yaml up --build
Tear down with the same -f files you brought it up with. mailpit and
seed exist only in the dev overlay, so a plain docker compose down -v does
not know about them: it deletes the network while those two are still attached,
and the next up creates a network with a new identifier that they no longer
point at. The result is Error response from daemon: network <id> not found,
which names the network rather than the containers actually at fault.
--remove-orphans covers the case where the overlay has already been forgotten.
To keep the data instead, rename inside each store before bringing the rest up.
Note the order for Postgres: renaming a role clears its password, so it has
to be set again afterwards, and a database cannot be renamed while you are
connected to it — hence -d postgres.
docker compose up -d postgres
docker compose exec postgres psql -U rt_erp -d postgres \
-c "ALTER ROLE rt_erp RENAME TO simple_erp;" \
-c "ALTER ROLE simple_erp WITH PASSWORD 'simple_erp_dev';" \
-c "ALTER DATABASE rt_erp RENAME TO simple_erp;"
docker compose up -d rabbitmq
docker compose exec rabbitmq rabbitmqctl add_user simple_erp simple_erp_dev
docker compose exec rabbitmq rabbitmqctl set_permissions -p / simple_erp ".*" ".*" ".*"
docker compose exec rabbitmq rabbitmqctl set_user_tags simple_erp administrator
# Photographs live in the bucket, and stored URLs name it. Copy, do not just
# create: minio-init makes an empty `simple-erp` bucket quite happily, and the
SimpleERP MCP questions
What does SimpleERP do?
It handles quoting, workforce management, and intervention planning, including travel time and lunch breaks, for home-care agencies.
How can I test the application with sample data?
The system includes a seeder that populates the database with 12 assistants, 40 customers, a service catalog, and 54 quotes upon startup.