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., "@ESGO MCP Server Find free capacity from 47057 Duisburg to 80331 München for 12 t next week."
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.
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.
Related MCP server: CargoEffe MCP Server
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-mcpVS 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 |
| your ESGO API key (required for calls) |
| optional, default |
The list comes from the API itself, so it may already be longer when you read this.
Tool | Endpoint | Changes data |
|
| no |
|
| no |
|
| yes |
|
| 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.
Python SDK: pypi.org/project/esgo
.NET SDK: nuget.org/packages/Esgo
API reference: api.es-go.de/v1/docs
Changelog: CHANGELOG.md
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.
Search matching capacity
Finds trips whose route, time and free capacity fit your shipment. Prices are non-binding estimates; a fixed price is the standing offer of the carrier. Counts against the daily quota "matches_search".
Required API key scope: matches:read.
| Name | Required | Description | Default |
|---|---|---|---|
| origin | Yes | Origin, ideally postcode and city. | |
| weight_kg | Yes | Cargo weight in kilograms. | |
| destination | Yes | Destination, ideally postcode and city. | |
| service_ids | No | Required additional services (ESGO service IDs). | |
| loading_meters | No | Loading meters needed (max 13.6). | |
| loading_requirement | No | How the cargo has to be loaded. "any" never filters; "seite" (side) and "oben" (top) exclude box bodies; "heck" means rear loading. | any |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, openWorld, non-destructive), but the description adds real operational context the annotations do not: it consumes a daily quota named "matches_search" and requires the matches:read scope. It also warns that prices are non-binding estimates, which is behaviorally useful. It stops short of describing pagination or result caps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense and front-loaded: the purpose sentence comes first, followed by pricing caveat, quota, and scope. The only waste is the leading line restating the title verbatim.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries some return-value burden and does partly address it by saying results are trips fitting route, time and free capacity, with non-binding prices. Quota and auth scope are also covered. A brief note on result ordering or limits would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all six parameters including the loading_requirement enum semantics. The description adds nothing beyond that, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource relationship: it "Finds trips whose route, time and free capacity fit your shipment." That is materially clearer than the title alone. It does not, however, distinguish itself from the sibling open_requests_list_matches, which an agent could plausibly confuse with this search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the inputs required (origin, destination, weight) and the quota/auth notes. There is no explicit statement of when to call this versus the sibling list-matches tool, and no exclusions or prerequisites beyond the read scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the current API key
Use this call to check that your key works and how many calls are left today. It needs no scope.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and openWorld, so the safety profile is covered. The description adds two pieces of context the annotations do not: no scope/authorization is required, and the response conveys remaining call quota — a quota-check behavior worth knowing. It doesn't describe what else is returned, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, and the actionable guidance is front-loaded after the purpose line. Every sentence earns its place by adding a use case or a constraint not already in the structured fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with full annotation coverage, the description supplies the key missing context: this is a health/quota check requiring no scope. With no output schema, it hints at the return value (calls left today) but does not fully describe what the payload contains, which is the only remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters, so according to the rubric the baseline is 4. There is nothing for the description to compensate for, and it correctly avoids inventing arguments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Retrieve the current API key') and goes beyond the title by explaining what the call is for: verifying the key works and checking remaining daily quota. The sibling tools (matches_search, open_requests_*) belong to an unrelated domain, so no differentiation is needed or expected. It loses a point only for leading with a restatement of the title.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use it: 'check that your key works and how many calls are left today,' which gives an agent a concrete triggering condition. It also notes the prerequisite is trivially satisfied ('It needs no scope'). No alternative tool is named, but no sibling competes for this task.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an open transport request
Posts a transport request that carriers on ESGO see. ESGO matches it against existing trips right away and against every new trip later. Counts against the daily quota "open_requests_create". Not retried automatically: a repeated call creates a second request.
Required API key scope: open_requests:write.
| Name | Required | Description | Default |
|---|---|---|---|
| origin | Yes | Origin, ideally postcode and city. | |
| weight_kg | Yes | Cargo weight in kilograms. | |
| cargo_type | Yes | Kind of cargo. | |
| destination | Yes | Destination, ideally postcode and city. | |
| service_ids | No | Required additional services (ESGO service IDs). | |
| time_windows | Yes | Pickup time windows; at least one. | |
| loading_meters | Yes | Loading meters needed (max 13.6). | |
| target_price_eur | No | Optional target price in EUR shown to carriers as orientation. | |
| cargo_description | No | Free text for the carrier. | |
| loading_requirement | No | How the cargo has to be loaded. "any" never filters; "seite" (side) and "oben" (top) exclude box bodies; "heck" means rear loading. | any |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds real behavioral context beyond the annotations: a repeated call creates a second request (reinforcing and explaining idempotentHint=false), the call is not retried automatically, it consumes a daily quota, and it requires the 'open_requests:write' API key scope. Open-world, quota, and non-idempotent semantics are all disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the purpose, then the matching behavior, then the quota/retry/auth constraints in short sentences. Slightly redundant in restating the title verbatim as the first line, but otherwise tight with no wasted prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter creation tool with no output schema, the description covers visibility, matching, quota, retry, and auth thoroughly. It does not indicate what the caller receives back (e.g., a request ID for later reference via open_requests_list_matches), which is the one remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with 10 well-documented parameters including enums, examples, ranges, and time-window semantics, so the schema carries the full burden. The description adds no parameter-level meaning beyond what the schema already states, which is the baseline 3 case.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Create an open transport request') and then explains the mechanism: the request is posted so carriers on ESGO see it and it is matched against existing and future trips. This is clearly distinguishable from the sibling read tools (matches_search, open_requests_list_matches), which only surface matches rather than creating requests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete operational context: the request is matched immediately against existing trips and continuously against new ones, and it counts against the daily 'open_requests_create' quota. It does not explicitly name the sibling tools or state when-not-to-use this versus them, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List matches of an open request
Trips ESGO has matched to one of your open requests, best first. Reading them does not mark them as seen in the dashboard.
Required API key scope: open_requests:read.
| Name | Required | Description | Default |
|---|---|---|---|
| request_id | Yes | ID of one of your open requests, as returned by open_requests_create. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description still adds real value beyond them: it discloses that reading matches does not mark them as seen in the dashboard, and it names the required API key scope (open_requests:read), both of which affect agent behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Compact and front-loaded: ordering ('best first'), the non-marking behavior, and the scope requirement each earn their place. The first line merely restates the title, which is mild redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with full schema coverage and no output schema, the description covers the essentials, including result ordering and the auth scope. It stops short of describing pagination or result shape, but nothing critical for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With a single parameter at 100% schema description coverage, the schema already documents request_id and even points to open_requests_create as its source. The description adds no further syntax or constraint detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (list) and resource (matches of an open request) and scopes it clearly to 'Trips ESGO has matched to one of your open requests'. It does not, however, name or distinguish itself from the sibling matches_search, which an agent could reasonably confuse it with.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: you need an existing open request (and its ID from open_requests_create) to call this. There is no explicit statement of when to prefer this over matches_search, nor any exclusion conditions, so the agent must infer the routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1matches_searchme_retrieveopen_requests_createopen_requests_list_matchesScored across 4 tools
matches_search and open_requests_list_matches both concern 'matches', which could cause some initial confusion, but the descriptions clearly separate proactive capacity search from listing matches of an existing request. me_retrieve and open_requests_create are unambiguous.
All names follow a consistent snake_case resource_action pattern (matches_search, open_requests_create, open_requests_list_matches, me_retrieve). Minor deviation: 'me_retrieve' and the compound action 'list_matches' break the clean resource_verb rhythm slightly, but the convention is still predictable.
Four tools is a lean but coherent set for a focused transport-matching API, covering auth check, capacity search, request creation, and match retrieval. It's on the thin side but each tool earns its place with no obvious filler.
The surface covers search, create, and match-listing, but there is no way to list one's own open requests, retrieve a single request, or update/cancel an existing request. These are notable lifecycle gaps for a request-management domain, though core workflows are usable.
Neutral freight reference + validation layer for AI agents: ADR, HS, UN/LOCODE, freight math
Open Transport Hub - transport and logistics marketplace directory for AI agents.
Geocoding, routing, isochrones, traffic, weather, and place search for AI agents. 19 MCP tools.
Routing, geocoding, places, matrix and map tools for location-aware AI workflows.
