Skip to main content
Glama

@muovi/mcp-server

npm version

Model Context Protocol (MCP) server for Muovi — LATAM's trust-first local services marketplace.

This package lets MCP-aware clients (Claude Desktop, Cursor, Claude Code, and any other MCP host) discover Muovi's verified LATAM service professionals, browse the service catalog and city list, read reviews, deep-link a user into the on-platform task-creation flow, and save a task draft the user publishes themselves. It is a thin wrapper over Muovi's public /v1 REST API.

Stdio mode. The package ships an npx-runnable binary that speaks JSON-RPC over stdin/stdout. The hosted HTTP/SSE variant is tracked separately (Muovi MOB-142).

What it exposes

Every tool is read-only except muovi_create_task_draft, which saves a draft on Muovi:

Tool

Wraps

Purpose

muovi_search_professionals

GET /v1/professionals

Up to 5 professionals for one service in one barrio. service and neighborhood are both required; every result has a coverage area that includes the barrio, and match names the service, barrio and city searched. Results list professionals who declare the searched trade first, ordered by review score, with verified identity, background check and matrícula counting toward it; professionals whose registered business is in another trade come last; there is no rating or review filter. Each result has one rating, one review_count, its verifications, up to 3 portfolio image URLs, an id and a profile_url (https://muovi.com.ar/profile/<id>), and no neighborhoods.

muovi_get_professional

GET /v1/professionals/{id}

Fetch a single pro's full public profile (bio, portfolio, specialties, verifications) by the id from the search. A ProSite slug from an older link is also accepted.

muovi_list_services

GET /v1/services

The full live service catalog — home trades (electricidad, plomería, gas, pintura, carpintería, cerrajería, albañilería, herrería, techista), limpieza, jardinería, aire acondicionado, plus moving/hauling: mudanzas (movers) and fletes (light freight).

muovi_list_cities

GET /v1/cities

Every Argentine city Muovi serves, with neighborhoods.

muovi_get_reviews

GET /v1/professionals/{id}/reviews

Paginated reviews for a pro, most-recent first, by the same id.

muovi_create_task_link

(pure formatter)

Builds a link to Muovi's own task creation for one professional (professional_id, the search's id) and one service: https://muovi.com.ar/post-task/v2?pro=<id>&vertical=<service>&source=assistant-link. It works for every professional in the results. A missing or malformed argument is a tool error. Makes no HTTP call.

muovi_get_service_requirements

GET /v1/services/{service_slug}/requirements

Lists the questions Muovi asks for one service (key, question in Spanish, type, accepted options, required or not), so the agent can ask the user before saving a draft.

muovi_create_task_draft

POST /v1/task-handovers

Saves a task draft (service, description, optional zone, preferred time and professional) and returns a link that expires in 24 hours if nobody opens it. The user opens it, reviews the draft, signs in and publishes it; the tool publishes nothing. With professional_id (the search's id), the published task goes to that pro first for 24 hours and then opens to everyone; with open_to_others: true it opens to everyone right away and that pro is still told. The user can change that choice on the review form.

Related MCP server: @qasperai/mcp-server

Anti-leakage policy

Muovi is on-platform-only. Phone, email, and WhatsApp handles are never returned by the public API — contact between consumers and professionals happens exclusively through Muovi's in-app conversation flow, reachable from each pro's profile_url.

This server enforces the policy twice:

  1. The /v1 API strips contact data server-side.

  2. Every tool response in this package also runs through a local anti-leakage detector (a Node-compatible mirror of src/lib/anti-leakage/detector.ts in the Muovi web repo). If a leak is detected at the agent boundary the tool returns a stable error to the LLM client and refuses to surface the payload.

Hosts that integrate this server must not synthesise off-platform contact handles from any field. Driving the user to profile_url (optionally with the deep-link query string) is the only sanctioned contact channel.

Installation & configuration

Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add the server under mcpServers:

{
  "mcpServers": {
    "muovi": {
      "command": "npx",
      "args": ["-y", "@muovi/mcp-server"]
    }
  }
}

If you have a Muovi API key (see Authentication below), pass it via env:

{
  "mcpServers": {
    "muovi": {
      "command": "npx",
      "args": ["-y", "@muovi/mcp-server"],
      "env": {
        "MUOVI_API_KEY": "your-key-here"
      }
    }
  }
}

Restart Claude Desktop after editing the config.

Cursor

Add to ~/.cursor/mcp.json (or your workspace's .cursor/mcp.json):

{
  "mcpServers": {
    "muovi": {
      "command": "npx",
      "args": ["-y", "@muovi/mcp-server"]
    }
  }
}

Claude Code

Register the server with the Claude Code CLI:

claude mcp add muovi --command "npx" --args "-y" "@muovi/mcp-server"

Or add it manually to your Claude Code settings:

{
  "mcpServers": {
    "muovi": {
      "command": "npx",
      "args": ["-y", "@muovi/mcp-server"]
    }
  }
}

Manual / scripting

npx -y @muovi/mcp-server

The process reads JSON-RPC on stdin and replies on stdout. All log output goes to stderr.

Authentication (optional)

All /v1 endpoints are public and unauthenticated by default. If your client has been issued a Muovi API key (higher rate-limit tier), set MUOVI_API_KEY in the server's environment and the package will forward it as the X-API-Key header on every request.

You can also override the API base URL for testing:

MUOVI_API_BASE_URL=https://staging.muovi.com.ar/api/v1 npx -y @muovi/mcp-server

muovi_create_task_link builds its link on MUOVI_WEB_BASE_URL when that is an https origin with no path, and on https://muovi.com.ar otherwise.

Example agent workflow

A typical Claude conversation that uses these tools:

  1. User asks for "an electrician in Palermo who's properly licensed".

  2. Agent calls muovi_list_services to map "electrician" → electricidad.

  3. Agent calls muovi_list_cities to confirm palermo is a valid neighborhood under caba.

  4. Agent calls muovi_search_professionals with { service: "electricidad", neighborhood: "palermo", has_matricula: true } and gets up to 5 professionals. Without both a service and a barrio the tool answers an error asking for them, so the agent asks the user first.

  5. Agent shows the results and offers two choices: a task for one of those professionals, or a general request to get offers from several.

  6. For one professional, the agent can call muovi_get_professional and muovi_get_reviews with that result's id.

  7. Agent calls muovi_create_task_link with { professional_id, service_slug: "electricidad" } and surfaces the resulting URL — or calls muovi_create_task_draft with { service_slug: "electricidad", professional_id, description } so the user lands on a draft already written. For a general request it calls muovi_create_task_draft without a professional.

  8. User follows the link, lands on Muovi, reviews the draft, signs in, and publishes the task in the on-platform flow.

Step 8 — the on-platform flow — is where the task is published, and where payments and disputes run.

Local development

This package is the standalone muovi-latam/mcp-server repo. Clone it, install, and run tests:

git clone git@github.com:muovi-latam/mcp-server.git
cd mcp-server
npm install
npm test            # unit + integration + OpenAPI drift checks
npm run typecheck   # strict TypeScript
npm run build       # emits dist/

The OpenAPI drift test parses public/openapi.yaml and asserts each tool's input schema matches the corresponding operation's parameters exactly — adding a query param to /v1 requires updating the corresponding tool (and vice versa).

Publishing

npm publish is intentionally not wired into CI. Releases are cut manually from a clean tag:

npm version patch    # or minor / major
npm publish --access public
git push --follow-tags

prepublishOnly runs clean + build + test before any publish.

MCP Registry (mcp-publisher)

Beyond npm, this server is listed in the Model Context Protocol registry via the committed server.json manifest. Publishing to the registry is a manual step — there is deliberately no CI auto-publish (the registry is a low-frequency, human-gated surface, and namespace auth is interactive).

Committed namespace: ar.com.muovi/mcp-server — the reverse-DNS form of muovi.com.ar. This value lives in both server.json (name) and package.json (mcpName) and the two must stay byte-identical (the server-json test enforces equality). It must also match the identity you authenticate as with mcp-publisher (see below).

One-time namespace ownership setup

Prove ownership of the ar.com.muovi namespace once, before the first publish:

  • DNS (preferred): add the TXT record that mcp-publisher login dns prints to the muovi.com.ar zone, then authenticate against that domain. This ties the namespace to the domain we already control.

  • GitHub OAuth (fallback): mcp-publisher login github — authenticates via the muovi-latam GitHub org. Only use this if DNS verification is unavailable; the authenticated identity still has to line up with the committed ar.com.muovi/mcp-server namespace.

If the committed namespace and the authenticated identity disagree, mcp-publisher publish will reject the manifest — fix the namespace (in both files) or the login, do not force it.

Publish steps

mcp-publisher validate ./server.json   # checks against the live registry schema
mcp-publisher publish                   # publishes server.json under the authenticated namespace

validate is the step that confirms the manifest matches the current registry schema version — run it every time; the pinned $schema in server.json is a hint, not a guarantee the live schema hasn't moved.

Version-bump discipline

The server-json test asserts that four version fields agree. On every version bump, update all of them together, then re-publish to both npm and the registry:

  1. package.json → version

  2. src/server.ts → PACKAGE_VERSION

  3. server.json → version

  4. server.json → packages[0].version

Honest gating notes

The manifest advertises capabilities that are not yet fully live. Keep these caveats in mind (and do not overstate them to users):

  • Remote transport (remotes[].url = https://mcp.muovi.com.ar/) is only truthful once that endpoint reliably answers JSON-RPC initialize over streamable-HTTP. That hosted surface is tracked in MOB-207; until it lands, the stdio package (npx @muovi/mcp-server) is the only transport that actually works.

  • muovi_create_task_draft answers "not available" while task handovers are switched off on the server (TASK_HANDOVERS_ENABLED), which is the default.

  • muovi_get_professional and muovi_get_reviews remain broken against production until MOB-263 deploys the backing /v1 endpoints. The tools are registered and pass drift checks, but live calls will fail until then.

License

MIT.

Available Tools

6 tools
muovi_get_professionalGet professionalA
Read-only
Inspect

Fetch the full public profile for a single Muovi-verified professional by slug. Returns display name, headline, bio, portfolio image URLs, specialties, city + neighborhoods, services, ratings, verifications, and the canonical profile_url. The profile_url is the only sanctioned contact channel — phone, email, and whatsapp are never returned. Append ?create_task=1&service={slug} to profile_url (or use muovi_create_task_link) to deep-link a user into the on-platform task creation flow targeted at this pro.

Inputs: slug (required).

muovi_get_reviewsGet reviewsA
Read-only
Inspect

Fetch paginated reviews for a single Muovi-verified professional, sorted most-recent first. Each review has a 1-5 rating, an optional title and free-text comment, the author's reduced display name (e.g. "María G." — full surnames are never returned), the author role (client or worker), the service category the review is associated with, and an ISO created_at timestamp. Use this to surface social-proof when recommending a professional.

Inputs: slug (required), limit, offset.

muovi_list_citiesList citiesA
Read-only
Inspect

List every Argentine city Muovi serves, with active neighborhoods nested under each. Each city has a stable slug (used as the city parameter on muovi_search_professionals) and a human-readable name. Each neighborhood has its own slug (used as the neighborhood parameter on muovi_search_professionals). Call this when you need to resolve a user's location wording to a Muovi city or neighborhood slug.

Inputs: no named parameters.

muovi_list_servicesList servicesA
Read-only
Inspect

List every service category Muovi supports in Argentina (electricidad, plomería, pintura, etc.). Each entry has a stable slug (used as the service parameter on muovi_search_professionals and muovi_create_task_link), a human-readable name, an optional description, and a requires_matricula flag indicating whether listed professionals must hold a verified professional license. Call this first when you need to map a user's natural-language request to a Muovi service slug.

Inputs: no named parameters.

muovi_search_professionalsSearch professionalsA
Read-only
Inspect

Search for verified service professionals in Argentina by service type, city, neighborhood, verification status, minimum rating, and minimum review count. Returns a paginated list of professionals with display name, headline, ratings, verifications, and a profile_url that is the only sanctioned contact channel (no phone/email/whatsapp is ever returned). Use this for discovery; use muovi_get_professional for the full detail payload.

Inputs: city, limit, offset, service, +5 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a unique functionality: creating a deep-link, fetching a professional profile, fetching reviews, listing cities, listing services, and searching professionals. There is no overlap or ambiguity between them.

    Naming Consistency5/5

    All tool names follow a consistent 'muovi_verb_noun' pattern using snake_case, such as muovi_list_cities and muovi_search_professionals. The naming is predictable and clear.

    Tool Count5/5

    With 6 tools, the server is well-scoped for its purpose of accessing Muovi professional services. Each tool is essential and covers distinct operations without unnecessary bloat.

    Completeness5/5

    The tool set covers the full lifecycle for the domain: listing locations and services, searching professionals, viewing detailed profiles and reviews, and generating a task creation link. No obvious gaps exist given Muovi's constraints (no server-side task creation).

    Maintenance

    ActivitySlowing
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Mercado Pago's Official MCP Server offers tools so that developers can easily interact with our API using natural language, which simplifies tasks and product integration. Remotely hosted by Mercadolibre supporting Streamable HTTP Transport. Details on how to connect: https://mcp.mercadopago.com/
      1
      9
      Apache 2.0
    • F
      license
      B
      quality
      B
      maintenance
      Read-only MCP server for Municipalidad de Rosario citizen queries, routing by intent to official sources and a local document index. It exposes tools for querying official documents, procedures, claims, payments, appointments, and news via MCP stdio or HTTP.
      10
      -
    • A
      license
      A
      quality
      A
      maintenance
      Unofficial Thumbtack MCP server for searching local service professionals and reading their profiles, ratings, reviews, and credentials. Read-only and anonymous.
      6
      203 npm
      MIT