ESGO API for AI assistants: search empty-run truck capacity and publish transport requests
Lets AI assistants (Claude, Cursor, VS Code, Windsurf and others that speak the Model Context Protocol) use the ESGO API: search for matching empty-run capacity in road freight and publish open transport requests, in plain language.
"Find free capacity from 47057 Duisburg to 80331 München for 12 t next week."
Alpha. The tools follow the ESGO API v1 automatically (see below).
Every operation of the ESGO API becomes one tool, built at start-up from the live OpenAPI spec at api.es-go.de/v1/openapi.json. When ESGO adds an endpoint, it is available as a tool the next time the server starts, without updating this package. If the API cannot be reached at start-up, the server uses the copy of the spec it ships with.
Tools that only read (me_retrieve, matches_search, open_requests_list_matches)
are marked read-only; tools that create data (open_requests_create) are not, so
your assistant asks before calling them.
You need an ESGO API key; there is no self-service sign-up yet. Request access at es-go.de/developers. The key stays on your machine and is only sent to the ESGO API.
The server runs locally and is started by your AI app. You need
uv; uvx downloads and runs the package on demand.
Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json),
Windsurf and others with the same format:
{
"mcpServers": {
"esgo": {
"command": "uvx",
"args": ["esgo-mcp"],
"env": { "ESGO_API_KEY": "esgo_live_..." }
}
}
}
Claude Code:
claude mcp add esgo -e ESGO_API_KEY=esgo_live_... -- uvx esgo-mcp
VS Code (.vscode/mcp.json):
{
"servers": {
"esgo": {
"command": "uvx",
"args": ["esgo-mcp"],
"env": { "ESGO_API_KEY": "esgo_live_..." }
}
}
}
Without uv: pip install esgo-mcp, then use esgo-mcp as the command.
| Variable | Meaning |
|---|---|
ESGO_API_KEY | your ESGO API key (required for calls) |
ESGO_BASE_URL | optional, default https://api.es-go.de |
The list comes from the API itself, so it may already be longer when you read this.
| Tool | Endpoint | Changes data |
|---|---|---|
me_retrieve | GET /v1/me | no |
matches_search | POST /v1/matches/search | no |
open_requests_create | POST /v1/open-requests | yes |
open_requests_list_matches | GET /v1/open-requests/{request_id}/matches | no |
Errors of the API (for example [429] daily_quota_exceeded or
[422] invalid_parameter (param: weight_kg)) are returned to the assistant as
tool errors, so it can correct the input or tell you.
MIT, see LICENSE.
Damit können KI-Assistenten (Claude, Cursor, VS Code, Windsurf und andere, die das Model Context Protocol sprechen) die ESGO API nutzen: passende Leerfahrten im Straßengüterverkehr suchen und offene Transportanfragen einstellen, in normaler Sprache.
So funktioniert es: Jeder Endpunkt der ESGO API wird zu einem Werkzeug. Der Server baut die Werkzeuge beim Start aus der aktuellen OpenAPI-Spezifikation. Neue Endpunkte sind damit beim nächsten Start da, ohne Update dieses Pakets. Ist die API beim Start nicht erreichbar, nimmt der Server die mitgelieferte Kopie. Werkzeuge, die Daten anlegen, sind entsprechend markiert; der Assistent fragt vorher nach.
Zugang: Du brauchst einen API-Schlüssel von ESGO, anzufragen unter es-go.de/developers. Der Schlüssel bleibt auf deinem Rechner und geht nur an die ESGO API.
Einrichtung: siehe die Konfigurationsbeispiele oben. Benötigt wird
uv; uvx esgo-mcp lädt und startet das Paket.
Lizenz: MIT, siehe LICENSE.
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
uvx esgo-mcpMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-esgo-logistics-esgo-mcp": {
"command": "uvx",
"args": [
"esgo-mcp"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referenceesgo-mcppypiESGO works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.