nomadmania-mcp

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 install nomadmania --marketplace malyushkin/nomadmania-mcp

Or the server alone:

claude mcp add nomadmania --env NM_TOKEN=<token> -- uvx --from git+https://github.com/malyushkin/nomadmania-mcp 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", "nomadmania-mcp"],
      "env": { "NM_TOKEN": "<token>" }
    }
  }
}

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

Tools

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.

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).

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.