Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@HERO Handwerk MCP Welche Angebote für Frau Schmidt sind noch offen?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Connect Claude, ChatGPT, Cursor and other AI assistants to HERO Handwerkersoftware. Ask about customers, projects, quotes, invoices and appointments in plain language — and turn phone calls or emails into new HERO projects without typing.
⚠️ Unofficial, community-built integration. Not affiliated with or endorsed by HERO Software GmbH.
Ask your assistant… | Tool used |
"Which quotes for Frau Schmidt are still open?" |
|
"What appointments do we have tomorrow?" |
|
"Show me all projects in Hamburg in status Angebot." |
|
"Find the customer number for Weber GmbH." |
|
"What does 15mm copper pipe cost in our catalogue?" |
|
"Create a project for this email enquiry." |
|
"Add a note to project 4711: customer called, wants appointment next week." |
|
Plus hero_schema and hero_graphql for anything else in the HERO API.
Related MCP server: Agency Handy MCP server
Read-only unless you opt in. Creating or changing data requires HERO_ALLOW_WRITES=true. In read-only mode even raw GraphQL mutations are refused.
Zero runtime dependencies. The whole server is a few hundred lines of TypeScript you can audit in minutes.
Your data stays between you and HERO. The server runs on your machine and talks only to the HERO API.
Ask HERO support for an API key (free for HERO customers). Keep it private — it gives access to your company data.
git clone https://github.com/<your-user>/hero-handwerk-mcp.git
cd hero-handwerk-mcp
npm install
npm run buildRequires Node.js 18+.
Edit claude_desktop_config.json (Settings → Developer → Edit Config):
{
"mcpServers": {
"hero": {
"command": "node",
"args": ["/absolute/path/to/hero-handwerk-mcp/dist/index.js"],
"env": {
"HERO_API_KEY": "your-api-key",
"HERO_ALLOW_WRITES": "false"
}
}
}
}Restart Claude Desktop. Other MCP clients (Cursor, Windsurf, VS Code, …) use the same command and env.
Variable | Default | Description |
| — (required) | API key from HERO support |
|
|
|
|
| API host |
|
| Request timeout |
Uses HERO's GraphQL API (/api/external/v7/graphql) and Lead API (/api/v1/Projects/create).
Reads the HERO schema via introspection, so arguments are typed correctly and undocumented types (appointments, products) are queried automatically. Wrong filter names get a clear error listing the valid ones.
npm test # builds and runs end-to-end tests against a mock HERO APIWant an AI assistant that answers the phone, drafts quotes or keeps your HERO data clean — set up and tailored to your Betrieb? Open an issue or get in touch.
Verbinden Sie Claude, ChatGPT & Co. mit Ihrer HERO Handwerkersoftware. Fragen Sie in normaler Sprache nach Kunden, Projekten, Angeboten, Rechnungen und Terminen — und legen Sie aus Anrufen oder E-Mails direkt neue Projekte in HERO an.
„Welche Angebote für Frau Schmidt sind noch offen?"
„Welche Termine haben wir morgen?"
„Leg für diese E-Mail-Anfrage ein Projekt an."
Sicher: Standardmäßig nur Lesezugriff. Schreiben nur mit HERO_ALLOW_WRITES=true. Läuft lokal, Daten gehen nur an HERO.
Einrichtung: API-Schlüssel beim HERO-Support anfragen → Schritte oben unter Setup folgen.
Inoffizielle Community-Integration, nicht von der HERO Software GmbH.
Einrichtung für Ihren Betrieb gewünscht? Melden Sie sich gern — wir richten KI-Assistenten für Handwerksbetriebe ein.
MIT
Add an entry to a project's logbook in HERO (e.g. a call note or site-visit summary). The exact argument names come from the HERO schema: call hero_schema and look at the add_logbook_entry mutation first, then pass them in arguments. Requires HERO_ALLOW_WRITES=true.
Inputs: arguments (required), selection.
Create a new customer enquiry/project in HERO via the Lead API (e.g. from a phone call, email or website form). Requires customer email and ZIP code. HERO de-duplicates customers by email. Requires HERO_ALLOW_WRITES=true. Always confirm the details with the user before calling.
Inputs: address (required), customer (required), comment, measure, +3 more.
Get full details for one or more projects by id: customer, contact person, site address, status, all documents (quotes, invoices, with PDF links) and the project logbook/history.
Inputs: ids (required).
Run a custom GraphQL query against HERO for anything the other tools don't cover. Read-only unless the server was started with HERO_ALLOW_WRITES=true. Use hero_schema to discover fields first.
Inputs: query (required), variables.
List calendar events/appointments (Termine) from HERO. Fields are selected automatically from the HERO schema. Pass date filters via filters (see hero_schema for calendar_events).
Inputs: offset, search, filters.
List contacts from HERO (customers by default). Use search to filter the returned page by name, company, email, phone or address. Returns id, customer number, name, company, email, phone and address.
Inputs: offset, search, filters, category.
List customer documents (quotes/Angebote, invoices/Rechnungen, order confirmations, ...) with number, type, net value, VAT, status and PDF link. Use search to filter, e.g. by document type name.
Inputs: offset, search, filters.
List products/articles from the HERO product catalogue (supply product versions), e.g. to look up prices or article numbers. Fields are selected automatically from the HERO schema.
Inputs: offset, search, filters.
List projects (HERO 'project matches') with project number, trade/measure, customer, site address and current status. Use search to filter by customer name, city, status, etc.
Inputs: offset, search, filters.
Explore the HERO GraphQL schema. Without arguments: lists all available queries and mutations with their arguments. With type: lists the fields of that type (e.g. the return type of calendar_events). Use this before hero_graphql or when you need filter arguments.
Inputs: type.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 10 tools
Each list tool targets a clearly distinct resource (customers, projects, documents, appointments, products), and get_project/create_lead/add_logbook_entry are unambiguous. The only mild overlap is hero_graphql, which is a generic escape hatch that can replicate anything, but its description frames it as a fallback so boundaries stay clear.
All tools use the hero_ prefix with a consistent verb_noun pattern (list_customers, get_project, create_lead, add_logbook_entry). hero_schema and hero_graphql deviate slightly by being bare nouns rather than verb_noun, but remain readable and predictable.
Ten tools is well-scoped for an ERP/CRM integration covering listing, detail retrieval, write actions, and a schema/query escape hatch. Each tool earns its place without redundancy.
The surface covers listing across the core resources, project detail, schema discovery, and two write operations, which is strong for a read-oriented integration. Detail-by-id lookups for customers/products/documents and update/delete operations are absent, but hero_graphql provides a workaround for those gaps.
Create contacts, move deals, send proposals and invoices, read your inbox, from Claude or ChatGPT.
Run a service business from your AI agent: CRM, leads, scheduling, invoicing, jobs and more.
Run a home-service business from your AI: jobs, customers, invoices, estimates, texts.
weclapp ERP in your AI assistant: reads instantly, writes only after a preview you approve.
