Local MCP server

The downloadable MCP server distribution allows you to deploy the server locally and use it with AI agents.

Prerequisites

The following components are required to run the local MCP server:

• Access key for the 2GIS API.
• AI client with MCP protocol support to interact with the local server.

Available tools and APIs

The MCP server provides the following tools:

Tool	Function	2GIS API used
search_poi	Searching for places and organizations by query and coordinates	Places API, Geocoder API
calculate_route	Building routes for various transport types, calculating travel time and distance	Routing API
geocode	Direct geocoding: converting an address to coordinates	Geocoder API
reverse_geocode	Reverse geocoding: converting coordinates to an address	Geocoder API
create_map_view	Creating a static map with markers in PNG format	Static API
calculate_isochrone	Building areas reachable from a starting point within a given time (isochrones)	Isochrone API

1. Get an access key

1. Sign up in the Platform Manager dashboard.

2. Get a key for the required APIs:

   • Get a free demo key (valid for 30 days, with request limits). The demo key has all the APIs required for the MCP server enabled automatically.

   • Purchase a subscription and create API keys. It is recommended to create two keys for the MCP server to separately control usage of maps and search APIs and routing APIs. The number of keys does not affect subscription cost. Recommended API distribution by keys:

     • One key for maps and search: Static API, Geocoder API, Places API.
     • One key for routing: Routing API, Isochrone API.

   If you create only one key, make sure all the APIs required for the MCP server are enabled. For more information about keys and subscriptions, see the account documentation.

For pricing details, see the Prices section.

2. Install and build the MCP server

1. Clone the MCP server repository.

2. Install dependencies:

   npm install

3. Build the MCP server:

   npm run build

   After the build, a dist/index.js file is created in the repository root. You will need to specify the path to this file in the launch configuration in the next step.

3. Connect the MCP server to an application

Claude Desktop

Add the 2GIS MCP server configuration to the claude_desktop_config.json settings file:

{
  "mcpServers": {
    "2gis": {
      "command": "node",
      "args": ["PATH_TO_REPO/dist/index.js"],
      "env": {
        "MAPGL_API_KEY": "YOUR_MAPS_API_KEY",
        "ROUTING_API_KEY": "YOUR_ROUTING_API_KEY"
      }
    }
  }
}

Where:

• PATH_TO_REPO - path to the MCP server repository folder containing the built dist/index.js file.
• YOUR_MAPS_API_KEY - your API key for maps and search.
• YOUR_ROUTING_API_KEY - your API key for routing. If you use a single key for all APIs, specify it in both variables.

If the server is deployed remotely (accessible via HTTP), use Supergateway:

{
  "mcpServers": {
    "2gis": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--streamableHttp",
        "https://YOUR_HOST/mcp"
      ]
    }
  }
}

LM Studio

LM Studio allows you to use the MCP server entirely locally, without cloud LLM providers. The model runs on your computer, while the MCP server only communicates with the 2GIS API.

Connect the MCP server following the instructions. Add the 2GIS MCP server configuration to the mcp.json settings file:

{
  "mcpServers": {
    "2gis": {
      "command": "node",
      "args": ["PATH_TO_REPO/dist/index.js"],
      "env": {
        "MAPGL_API_KEY": "YOUR_MAPS_API_KEY",
        "ROUTING_API_KEY": "YOUR_ROUTING_API_KEY"
      }
    }
  }
}

Where:

• PATH_TO_REPO - path to the MCP server repository folder containing the dist/index.js file.
• YOUR_MAPS_API_KEY - your API key for maps and search.
• YOUR_ROUTING_API_KEY - your API key for routing. If you use a single key for all APIs, specify it in both variables.

Cursor

Add the 2GIS MCP server configuration to the .cursor/mcp.json settings file:

{
  "mcpServers": {
    "2gis": {
      "command": "node",
      "args": ["PATH_TO_REPO/dist/index.js"],
      "env": {
        "MAPGL_API_KEY": "YOUR_MAPS_API_KEY",
        "ROUTING_API_KEY": "YOUR_ROUTING_API_KEY"
      }
    }
  }
}

Where:

• PATH_TO_REPO - path to the MCP server repository folder containing the built dist/index.js file.
• YOUR_MAPS_API_KEY - your API key for maps and search.
• YOUR_ROUTING_API_KEY - your API key for routing. If you use a single key for all APIs, specify it in both variables.

VS Code (GitHub Copilot)

Create a .vscode/mcp.json file in the workspace root and add the 2GIS MCP server configuration:

{
  "servers": {
    "2gis": {
      "command": "node",
      "args": ["PATH_TO_REPO/dist/index.js"],
      "env": {
        "MAPGL_API_KEY": "YOUR_MAPS_API_KEY",
        "ROUTING_API_KEY": "YOUR_ROUTING_API_KEY"
      }
    }
  }
}

Where:

• PATH_TO_REPO - path to the MCP server repository folder containing the built dist/index.js file.
• YOUR_MAPS_API_KEY - your API key for maps and search.
• YOUR_ROUTING_API_KEY - your API key for routing. If you use a single key for all APIs, specify it in both variables.

Any MCP-compatible client

The 2GIS MCP server uses the standard MCP protocol over stdio. Any application that supports the MCP protocol can connect to the server by specifying the launch command:

MAPGL_API_KEY=YOUR_MAPS_API_KEY ROUTING_API_KEY=YOUR_ROUTING_API_KEY node dist/index.js

Where:

• YOUR_MAPS_API_KEY - your API key for maps and search.
• YOUR_ROUTING_API_KEY - your API key for routing. If you use a single key for all APIs, specify it in both variables.