# Xentral MCP Server

**English** · [Deutsch](docs/README.de.md)

**Connect Xentral to Claude, ChatGPT and Copilot: articles, customers, sales orders, invoices and stock as AI tools as MCP tools.** Powered by [AnythingMCP](https://github.com/HelpCode-ai/anythingmcp).

Xentral MCP Server gives Claude, ChatGPT, Copilot and Cursor 7 tools for Xentral: articles, customers, sales orders, invoices and stock as AI tools. Every tool only reads. It runs on AnythingMCP: one click on AnythingMCP Cloud, or self-hosted with Docker. Credentials are stored encrypted and every call is audited.

**Status:** not yet verified against a live system. The adapter follows the vendor's API documentation; please report what you find.  
**Adapter synced:** <!-- synced -->2026-09-26

Maintained by [KOCH Freiburg GmbH](https://www.kochfreiburg.de/), which runs AnythingMCP in production. Built on [AnythingMCP](https://github.com/HelpCode-ai/anythingmcp) by helpcode.ai.

## Quick start (AnythingMCP Cloud)

1. Sign in at [cloud.anythingmcp.com](https://cloud.anythingmcp.com) and open the [install link](https://cloud.anythingmcp.com/connectors/store?install=xentral).
2. Enter `XENTRAL_URL`, `XENTRAL_USER`, `XENTRAL_PASSWORD` (see [Authentication](#authentication)).
3. Copy the URL of your MCP server under **MCP Servers** and add it to your AI client ([below](#connect-claude-chatgpt-copilot-or-cursor)).

AnythingMCP Cloud is the same open-source code, operated by helpcode.ai in Frankfurt, Germany.

## Self-hosted (Docker)

Needs Docker 24+, openssl and Node 18+.

```bash
git clone https://github.com/kochfreiburg/xentral-mcp-server.git
cd xentral-mcp-server
./scripts/install.sh
```

`install.sh` writes `.env` with fresh secrets, starts AnythingMCP, creates the first admin, installs the connector if `XENTRAL_URL` and `XENTRAL_USER` and `XENTRAL_PASSWORD` are set in `.env` and creates an MCP API key. Without credentials it prints the install link instead: `http://localhost:3000/connectors/store?install=xentral`. Then check the whole chain:

```bash
npm install && node scripts/smoke.mjs
```

## Connect Claude, ChatGPT, Copilot or Cursor

- **Claude (claude.ai, Desktop, mobile):** *Customize → Connectors → Add custom connector*, paste your MCP server URL and sign in. Claude connects from Anthropic's cloud, so the URL must be public HTTPS: your AnythingMCP Cloud URL, or your own instance behind TLS.
- **Claude Code:**

  ```bash
  claude mcp add --transport http xentral-mcp-server http://localhost:4000/mcp --header "X-API-Key: <MCP_API_KEY>"
  ```
- **Cursor** (`.cursor/mcp.json`) and **VS Code / GitHub Copilot** (`.vscode/mcp.json`, key `servers` instead of `mcpServers`, plus `"type": "http"`):

  ```json
  { "mcpServers": { "xentral-mcp-server": { "url": "http://localhost:4000/mcp", "headers": { "X-API-Key": "<MCP_API_KEY>" } } } }
  ```
- **ChatGPT:** add the public HTTPS URL as a connector (app) in ChatGPT's settings. A `localhost` URL does not work there.

## Tools

7 tools, generated from [`adapter/xentral.json`](adapter/xentral.json). **read** tools cannot change anything in the source system.

<!-- tools:start (generated from adapter/*.json, do not edit) -->
| Tool | What it does | Access |
|---|---|---|
| `xentral_list_articles` | List articles (products) from Xentral. | read |
| `xentral_get_article` | Retrieve a single article by its Xentral internal id. | read |
| `xentral_list_customers` | List customers (Kunden). | read |
| `xentral_get_customer` | Retrieve a single customer by id, including contact persons, delivery addresses, bank details, and credit limit. | read |
| `xentral_list_sales_orders` | List sales orders (Auftraege). | read |
| `xentral_list_invoices` | List outgoing invoices (Rechnungen). | read |
| `xentral_get_stock` | Retrieve current stock levels across all warehouses for a given article. | read |
<!-- tools:end -->

## Example prompts

- Which sales orders from this week are still open?
- How much stock of article 100245 do we have in each warehouse, and how much is reserved?
- Which invoices are still open, and for how much?
- Show customer 10023 with their contact persons and payment terms.
- What was our invoiced total last month?
- Find the customer "Bauer Holzbau" and list their last five orders.

More in [examples/prompts.md](examples/prompts.md).

## Authentication

This connector uses the Xentral v1 REST API.

**Instance URL**: Xentral is self-hosted per tenant. Paste your instance URL (without trailing slash) into `XENTRAL_URL` when importing — e.g. `https://koch.xentral.biz`. Do NOT append `/api`; the adapter handles that.

**Credentials**: the classic API uses Basic authentication. Generate an API user in your Xentral instance under Einstellungen → Benutzer → API. The username is the API user's login, the password is its password. Set them as `XENTRAL_USER` and `XENTRAL_PASSWORD` at import time.

**Entities covered**: articles (products), customers, sales orders (`/Auftrag`), invoices (`/Rechnung`), vendors, stock levels (`/Lager`), addresses.

**Pagination**: list endpoints accept `page` and `items_per_page`. Default is 50 items per page.

**Filtering**: use `filter` query parameter with Xentral filter DSL — e.g. `?filter=customer_number:eq:10001`.

**Webhooks**: Xentral also supports webhooks for real-time events (configured in-instance, outside this adapter).

## Security

- **Read or write is your choice.** All 7 tools only read. Assign the connector to an MCP server whose role whitelists only the tools you want, and the rest are invisible to that client.
- **Credentials** are encrypted with AES-256-GCM and never shown to the model.
- **Response mapping** drops or reshapes fields per tool before they reach the model, e.g. bank details or personal data.
- **Audit log:** every call is recorded with input, output, duration and status, in your own database when self-hosted.
- **SSO, RBAC and SCIM** are included in the self-hosted build.

## FAQ

### Is there a Xentral MCP server?
Yes, this one. It connects the Xentral REST API to Claude, ChatGPT and Copilot through AnythingMCP: 7 tools for articles, customers, sales orders, invoices and stock per warehouse.

### What do I need to connect it?
Your Xentral instance URL and an API user (Einstellungen → Benutzer → API), whose login and password the connector uses for Basic authentication.

### Can the AI change data in Xentral?
No. All seven tools only read.

### Has this been tested against a live Xentral instance?
Not yet: the adapter follows the Xentral API documentation. If you use Xentral, a report of what works is very welcome.

### Does it work with ChatGPT and Copilot?
Yes. The same MCP server works in ChatGPT (with a public HTTPS URL such as AnythingMCP Cloud), GitHub Copilot in VS Code, Cursor and Claude Code.

## Troubleshooting

| Problem | Fix |
|---|---|
| `401` / `403` from the vendor | The credentials are wrong or lack rights. Re-enter them on the connector page; the import runs a test call and shows the result. |
| Tools missing in the AI client | The connector is not assigned to the MCP server the client uses. Check **MCP Servers**, then run `node scripts/smoke.mjs`. |
| The host is on your internal network | Self-host AnythingMCP on that network and add the hostname to `SSRF_ALLOWED_HOSTS`, or the outbound guard blocks the call. |
| Works locally, fails on AnythingMCP Cloud | The system must be reachable from the internet with a valid TLS certificate. |

## Related

- [erp-mcp-server](https://github.com/HelpCode-ai/erp-mcp-server): ERP MCP server: connect 16 ERPs (SAP, Odoo, JTL-Wawi, Xentral, weclapp, ERPNext…) to Claude & ChatGPT. Self-hosted or cloud.
- [weclapp-mcp-server](https://github.com/kochfreiburg/weclapp-mcp-server): weclapp MCP server: connect weclapp Cloud ERP to Claude & ChatGPT. Customers, orders, invoices, quotes and opportunities.
- [billbee-mcp-server](https://github.com/kochfreiburg/billbee-mcp-server): Billbee MCP server: connect Billbee order management to Claude & ChatGPT. Orders, products, customers and shipping providers.
- [AnythingMCP](https://github.com/HelpCode-ai/anythingmcp): the open-source MCP server and gateway this repository is built on.

## License

AGPL-3.0-only. The adapter definition in `adapter/` comes from AnythingMCP (AGPL-3.0).