macola-mcp
# macola-mcp
An **unofficial** [MCP](https://modelcontextprotocol.io) server for the **Macola 10 REST API**. It lets Claude (or any MCP client) look up and, if you allow it, update your Macola data: customers, contacts, addresses, customer orders, inventory, prices, purchase orders, GL accounts and more. 88 tools in all.
> **Not affiliated with or endorsed by ECI Software Solutions.** "Macola" is a trademark of its owner. This project contains no Macola code or documentation; it only calls the REST API that your own licensed Macola 10 installation provides.
## Highlights
- **Windows sign-in, no stored password.** Each request is made as the Windows user running the MCP client (Kerberos), so people get their own Macola rights and Macola records changes under their own name.
- **Read-only by default** in the desktop extension. Turn it off only when you want Claude to create, change or delete records.
- **One-click install** for Claude Desktop (`.mcpb` extension): no Node.js, Git or scripts needed on the PC.
## Requirements
- Macola 10 with the **REST API** installed (built against Macola 10.7; check `http://<server>/Macola/api/docs/index`).
- A Windows 10 (1803+) or Windows 11 PC joined to the same domain as the Macola server. The built-in `curl.exe` does the sign-in.
- Each user needs Macola rights for what they look up or change (see *Troubleshooting*).
## Install (Claude Desktop)
1. Download `macola.mcpb` from [Releases](../../releases), or build it yourself (below).
2. Double-click it (or Claude Desktop → Settings → Extensions → Install Extension).
3. Enter your **Macola server name**, e.g. `ERPSERVER` (it becomes `http://ERPSERVER/Macola/api`). Use the server's **name**, not its IP address; Kerberos needs the name. A full address such as `https://erp.example.local/Macola/api` also works.
4. Leave **Read-only** on until you're comfortable.
## Install (any MCP client, manual)
```bash
git clone <this repo> && cd macola-mcp
npm install && npm run build
```
Then add it to your client's config, for example Claude Desktop's `%APPDATA%\Claude\claude_desktop_config.json`:
```json
{
"mcpServers": {
"macola": {
"command": "node",
"args": ["C:\\path\\to\\macola-mcp\\dist\\index.js"],
"env": {
"MACOLA_SERVER": "YOUR-MACOLA-SERVER",
"MACOLA_AUTH": "windows",
"MACOLA_READONLY": "true"
}
}
}
}
```
### Other MCP clients
It runs as a **local** (stdio) MCP server, so it works with any client that can start one. It does **not** work with the ChatGPT app or website: those only connect to MCP servers hosted on the internet, and this one runs on the user's PC so it can sign in as that Windows user.
**OpenAI Codex CLI**: `%USERPROFILE%\.codex\config.toml`
```toml
[mcp_servers.macola]
command = "node"
args = ["C:\\path\\to\\macola-mcp\\dist\\index.js"]
env = { MACOLA_SERVER = "YOUR-MACOLA-SERVER", MACOLA_AUTH = "windows", MACOLA_READONLY = "true" }
```
**VS Code (GitHub Copilot agent mode)**: `.vscode/mcp.json` in your workspace (or run "MCP: Add Server")
```json
{
"servers": {
"macola": {
"type": "stdio",
"command": "node",
"args": ["C:\\path\\to\\macola-mcp\\dist\\index.js"],
"env": { "MACOLA_SERVER": "YOUR-MACOLA-SERVER", "MACOLA_AUTH": "windows", "MACOLA_READONLY": "true" }
}
}
}
```
**Cursor / Windsurf / Claude Code**: same `mcpServers` block as the Claude Desktop example above (Cursor: `%USERPROFILE%\.cursor\mcp.json`; Claude Code: `claude mcp add macola -e MACOLA_SERVER=YOUR-MACOLA-SERVER -e MACOLA_READONLY=true -- node C:\path\to\macola-mcp\dist\index.js`).
### Settings
| Variable | Meaning |
|---|---|
| `MACOLA_SERVER` | **Required.** Your Macola server's name, e.g. `ERPSERVER` (becomes `http://ERPSERVER/Macola/api`) |
| `MACOLA_BASE_URL` | Instead of `MACOLA_SERVER`: the full API address, for non-standard setups (HTTPS, other path or port) |
| `MACOLA_AUTH` | `windows` (default): sign in as the current Windows user. `basic`: fixed account from `MACOLA_USERNAME` / `MACOLA_PASSWORD` (avoid if you can) |
| `MACOLA_READONLY` | `true`: only read tools are offered (61 of 88). Unset or `false`: all tools, including create/update/delete |
| `MACOLA_CURL` | Optional path to a `curl.exe` with SSPI. Default: `%windir%\System32\curl.exe`, then Git for Windows' curl |
## What it covers
Addresses, contacts, customer orders and order lines (including credit-hold removal and create-from-master), customer items, comment codes, inventory items, locations, bins, kits, serial/lots, in-transit, feature options, product categories, substitute items, inventory transactions, warehouse locations, purchase orders and lines, GL accounts, cost centers and units, pricing, divisions, receivable terms, projects, job titles, titles, tax codes and schedules, shop floor orders, standard routings, and ForecastPro export/import.
Every "find" tool accepts the API's common query options (`pageSize`, `page`, `skip`, `fields`, `order`, ...), and any property name works as a filter.
## Troubleshooting
| Symptom | Cause / fix |
|---|---|
| `401` "Windows sign-in was not accepted" | Use the server **name** in `MACOLA_SERVER` (not an IP), and run on a domain-joined PC signed in with a domain account |
| `403` "Access Denied. Insufficient rights" | The signed-in user has no Macola rights for that resource. Grant them in Macola |
| Reading contacts works, but **saving a contact gives a bare 500** | The Macola API forwards contact saves to Synergy as the user, and the update (HTTP MERGE) needs **write permission on Synergy's `services\Exact.Entity.REST.svc` file** (ASP.NET file authorization, 401.3 behind the scenes). Grant the user, or better an AD group, **Modify** on that one file. No restart needed |
| 500 when filtering by `Account` | `Account` filters need the account's GUID, not the customer number |
| 500 with `totalCount` on CustomerItem / ProductCategory | An API quirk; those tools drop `totalCount` |
## Known limitations
- `forecast_pro_import` has not been tested against a live system.
- Windows only (Windows sign-in relies on SSPI). `MACOLA_AUTH=basic` works anywhere Node runs.
## Build the desktop extension
```powershell
pwsh .\build-extension.ps1 # -> release\macola.mcpb
```
## Contributing
Issues and pull requests are welcome, especially reports of which tools work on other Macola versions. Please never include customer data, server names or credentials in issues, logs or screenshots.
## License
[MIT](LICENSE). Provided as is, without warranty: test with read-only mode first, and review what Claude proposes before allowing changes.
TDQS
Scored across 88 tools
Most tools target distinct resources and actions, but the large surface creates several close pairs such as locations_find/locations_get versus inventory_locations_find/inventory_locations_get, and addresses_find versus addresses_address_book. Descriptions help, but an agent must carefully distinguish many find/get pairs across similar ERP entities.
The dominant convention is clear snake_case with an entity prefix followed by an action (addresses_find, purchase_orders_create, inventory_items_get). There are minor deviations such as singular/plural inconsistencies (purchase_orders vs purchase_order_lines, standard_routing), awkward names like addresses_address_book, and special action names like customer_orders_remove_credit_hold.
With 88 tools, the server is far beyond a practical MCP tool surface and will be difficult for an agent to navigate efficiently. Although the ERP domain is broad, the set is bloated with many repetitive find/get pairs and would benefit from consolidation or resource-oriented grouping.
Core sales, purchasing, inventory, and contact/address workflows are broadly covered, with several resources supporting full CRUD. However, many resources are read-only or partially covered, such as inventory_items, projects, shop_floor_orders, locations, and tax codes, leaving notable lifecycle gaps.