Skip to main content
Glama

Unofficial and unaffiliated. NomadMania is a trademark of NomadMania OÜ. This project is not affiliated with, endorsed by or supported by NomadMania. Please do not contact them about bugs in this tool.

An MCP server for your own NomadMania profile. An AI agent can read the profile, find series objects and unvisited regions near a point, list and edit trips, and tick a series object. Every write is a preview until the agent passes confirm=true, and every write is read back to check it landed.

It is built on faeton/wanderfill, an unofficial client for NomadMania's private API that does the hard part: the API client, the tile reader and the region catalogue. This repo adds the MCP layer and the series and trip logic on top. API facts confirmed live: docs/live-facts.md.

Try asking

  • "Which World Capitals within 200 km of Vienna haven't I ticked yet?"

  • "What counts as a visit for UNESCO World Heritage Sites?"

  • "I crossed the Croatia-Montenegro border last week. Tick it."

  • "Which regions within 500 km of Lisbon have I not visited?"

  • "Show my trips for this year, with the dates in each region."

Related MCP server: Travel Planning MCP

Install

You need uv and a NomadMania token: on nomadmania.com, run localStorage.getItem('token') in the browser console. The token is valid for about a year and gives full access to your account, so keep it private.

Claude Code

As a plugin. It asks for the token and adds the agent rules from skills/nomadmania:

/plugin marketplace add malyushkin/nomadmania-mcp
/plugin install nomadmania@nomadmania-mcp

Or the server alone:

claude mcp add nomadmania --env NM_TOKEN=<token> -- uvx --from git+https://github.com/malyushkin/nomadmania-mcp@v0.6.0 nomadmania-mcp

Cursor, VS Code

Install links: Cursor (fill in NM_TOKEN in the install dialog), VS Code (asks for the token).

Other MCP clients

{
  "mcpServers": {
    "nomadmania": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/malyushkin/nomadmania-mcp@v0.6.0", "nomadmania-mcp"],
      "env": { "NM_TOKEN": "<token>" }
    }
  }
}

NM_CACHE_DIR (default ~/.cache/nomadmania-mcp) holds the region catalogue and map tiles.

Tools

Tool

What

profile_summary

Account id, the scores the profile page shows, visited region count

list_series

All 69 series: id, name, object count

series_rules

A series' description as plain text, read live: the only place its visit rule is stated

series_near

Series objects within radius_km (≤200) of a point, nearest first, with ticked

series_items

One series' objects from its catalogue, pinned or not, filtered by name/country, with ticked

save_trip

Preview by default; edits (trip_id) or creates a trip with confirm=true, then finds it again to verify

trips_for_year

Trips entered in NomadMania for a year, newest first, with dated legs (region per stretch of the route)

unvisited_regions_near

Regions not marked visited within radius_km (≤1500), nearest first, plus visited count

tick_series_item

Preview by default; ticks with confirm=true, then re-reads to verify (verified, also_ticked, scores_changed)

The writes are tick_series_item and save_trip. One place has a different id in each series (Rome: 82 in World Capitals, 1692 in European Cities), so the preview lists likely_also by name and position, and the result reports what actually got ticked. Objects without a map pin (Borders country pairs) come from series_items and tick without lat/lon. A Borders pair has a second box, "other border crossing between same countries": other_crossing=true ticks it, only once the first box is ticked. Experiences (17) and Top of the tops (-2) are read-only. There is no untick.

save_trip posts what the site's trip form posts (trips/update-trip, trips/new-trip): the whole trip, not a patch. An edited trip can come back under a new trip_id, so verification finds it by title and legs. There is no trip delete.

Collection export

nm-collection-export is a separate command, not an MCP tool. It prints your regions as JSON, each with the date of its first visit (transit and future trips don't count), its number in the collection and the running country count. It only reads. Regions marked visited without a dated trip are listed on stderr.

uv run nm-collection-export > collection.json

For AI agents

The plugin loads these rules as a skill; with the server alone, give them to your agent yourself (skills/nomadmania/SKILL.md has the full list).

  • Writes (tick_series_item, save_trip) return a preview by default. Show it to the user and pass confirm=true only after they agree.

  • There is no untick and no trip delete. A wrong write has to be fixed by hand on the site.

  • Read series_rules before telling the user what counts as a visit. The rule lives only in the series description.

  • A tick can also tick the same place in other series. Check also_ticked in the result.

  • A warning from a geo tool means every tile came back empty. That usually means the network failed.

Development

uv sync
printf 'NM_TOKEN=...\n' > .env && chmod 600 .env
uv run nomadmania-mcp

Updating wanderfill

wanderfill is pinned to a commit in pyproject.toml ([tool.uv.sources]), because it is alpha and wraps a private API. To update:

  1. Set rev to the new commit, run uv lock.

  2. uv run pytest, then a live series_near and unvisited_regions_near.

  3. Bump the version (pyproject.toml, badge, CHANGELOG.md with the new rev).

  4. After merge, tag the release (git tag vX.Y.Z) and move the @vX.Y.Z pin in the install commands, the Cursor/VS Code links and .claude-plugin/plugin.json.

scripts/probe.py dumps real API answers into .probe/ (git-ignored) to check a fact before changing the synthetic fixtures (tiles needs no token, api does).

Tests

uv run pytest. The fixtures in tests/fixtures/ are synthetic: a few hand-placed objects around Rome, made-up trips and account id 12345. scripts/make_fixture_tiles.py writes the map tiles. The repo holds no real profile data and no NomadMania catalogue.

For NomadMania

If you would like this changed or taken down, open an issue and it will happen.

This project ships none of NomadMania's data: no catalogue, no polygons, no tiles. Everything is fetched at runtime with the user's own token, and the server only does what an account holder can do on the site with their own profile. Anything that looks like a missing authorisation check gets reported privately and stays out of this repo.

License

Apache-2.0, same as wanderfill. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to read Marriott Bonvoy account details, stays, trips, and hotel availability, and to create, modify, or cancel reservations through a real Chrome session, with all writes gated on explicit human confirmation.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Provides AI agents with a structured API for travel planning, enabling them to read trip data, search places, calculate routes, and create/validate itinerary change proposals that require explicit human approval before being applied.
      15
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Lets an MCP-compatible agent view and build Wanderlog trip itineraries conversationally, adding places, notes, hotels, transit, car rentals, checklists, expenses, and searching places, hotels, and guides. It enables creating and editing full trips, day sections, and budget entries without clicking through the Wanderlog UI.
      428 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables an MCP-compatible agent to build, read, and edit Wanderlog trip itineraries through conversation — adding places, notes, hotels, transit, checklists, and expenses, plus searching places, guides, and hotel deals. Supports creating trips, adjusting dates, renaming days, managing custom sections, and retrieving shareable links.
      428 npm
      MIT