HERO Software MCP server
# HERO Software MCP server through Cotlet.dev
Connect HERO Software to ChatGPT, Claude, Codex and Claude Code through Cotlet.dev. Turn inquiries into contacts and projects, draft quotes, prepare invoices and brief your crew from the calendar.
This is an unofficial integration, not affiliated with HERO Software. Cotlet.dev hosts the connection through your own signed-in Cloud Browser. This repository provides an optional Python stdio MCP bridge.
## Connect your account
1. [Request access to HERO Software](https://cotlet.dev/signup?app=hero-software).
2. Open https://login.hero-software.de in your Cotlet.dev Cloud Browser and sign in with your own HERO user. Enable HERO Software for agents.
3. Connect your agent. Refresh the connector if you enabled HERO after connecting.
### ChatGPT
Open Settings > Apps & Connectors > Create. Enter `https://cotlet.dev/mcp/v1/connect` as the MCP server URL and choose OAuth.
### Claude
Open Settings > Connectors > Add custom connector and enter `https://cotlet.dev/mcp/v1/connect`.
### Codex
Create a Cotlet.dev API key in your console and set `COTLET_API_KEY` in your environment:
```toml
[mcp_servers.cotlet]
url = "https://cotlet.dev/mcp/v1"
bearer_token_env_var = "COTLET_API_KEY"
```
### Claude Code
```bash
claude mcp add --transport http cotlet https://cotlet.dev/mcp/v1 --header "Authorization: Bearer $COTLET_API_KEY"
```
## Trade office workflows
Examples from the [live HERO Software integration reference](https://cotlet.dev/integrations/hero-software-api-mcp-server):
- Search the customer index before creating a contact and project for a new inquiry.
- Draft a quote using quantities, prices and VAT rates you provide.
- Read an accepted quote, confirm creating its invoice, then separately approve emailing it.
- Review overdue invoices and the project logbook before approving a payment reminder.
- Brief the crew using appointments and open tasks.
- Add site notes to a project logbook or create a calendar appointment.
The live reference lists 15 hosted capabilities: 7 read and 8 write, grouped under `hero_software_read` and `hero_software_write`:
- `list_projects`
- `get_project`
- `list_contacts`
- `create_contact`
- `create_project`
- `add_logbook_entry`
- `list_documents`
- `get_document`
- `create_quote`
- `create_invoice_from_quote`
- `send_document`
- `send_payment_reminder`
- `list_appointments`
- `list_tasks`
- `create_appointment`
`create_invoice_from_quote`, `send_document` and `send_payment_reminder` ask for approval by default; this can be changed per tool. The other five writes change your HERO account immediately. Quotes and invoices stay in the project until `send_document` emails them. Prices come from you or your article data. Check recipients, totals and VAT before approving. Emailed documents cannot be recalled. Creating an appointment does not email the customer.
## Optional local stdio bridge
Python 3.10 or newer is required, with no runtime dependencies. Clone this repository and configure a client that supports stdio:
```json
{"mcpServers":{"hero-software":{"command":"python3","args":["/absolute/path/to/hero-software-mcp/hero_software_agent.py"],"env":{"COTLET_API_KEY":"your-cotlet-key"}}}}
```
The bridge lists seven browser helpers: `hero_software_guide`, `hero_software_status`, `hero_software_open`, `hero_software_read`, `hero_software_click`, `hero_software_type` and `hero_software_close`. These forward to Cotlet.dev's shared browser tools; they are separate from the 15 hosted workflow capabilities. Call the guide first and close the browser when finished. Discovery works without a key. Execution requires your Cotlet.dev key and connected account.
```bash
python3 hero_software_agent.py connect
python3 hero_software_agent.py guide
python3 hero_software_agent.py status
python3 hero_software_agent.py serve
```
You can also build the included Dockerfile and pass `COTLET_API_KEY` as an environment variable.
## Reference and access
- [HERO Software connection guide and operation reference](https://cotlet.dev/integrations/hero-software-api-mcp-server?utm_source=github&utm_medium=readme&utm_campaign=hero-software)
- [Request access](https://cotlet.dev/signup?app=hero-software)
- [Cotlet.dev console](https://cotlet.dev/app)
Licensed under Elastic License 2.0. See LICENSE.
TDQS
Scored across 7 tools
Each tool has a clearly distinct role: guide explains the system, status checks account readiness, and open/read/click/type/close form a non-overlapping browser-action sequence. There is no confusion about which tool to pick for a given step.
All tools share the consistent hero_software_ prefix followed by a concise verb (open, read, click, type, close) or clearly labeled noun (guide, status). The snake_case convention is uniform throughout.
Seven tools is well-scoped for a browser-automation workflow, with each tool earning its place. No redundant or filler tools are present.
The surface covers the full browser lifecycle (open, read, click, type, close) plus onboarding (guide) and health (status). Minor gaps like scroll or explicit navigation beyond open are not covered but most workflows can work around them.