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. Select all the APIs required for the MCP server during the purchase process. The first access key is created automatically after the subscription is activated.

     Using two keys

     If you need to control usage of maps and search APIs and routing APIs separately, it is recommended to create two keys for the MCP server. 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.

   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_API_KEY",
        "ROUTING_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Where:

• PATH_TO_REPO - path to the MCP server repository folder containing the built dist/index.js file.

• YOUR_API_KEY - your API key for accessing 2GIS services.

  If you use separate keys for maps and search and for routing, specify them in the MAPGL_API_KEY and ROUTING_API_KEY variables, respectively.

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_API_KEY",
        "ROUTING_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Where:

• PATH_TO_REPO - path to the MCP server repository folder containing the dist/index.js file.

• YOUR_API_KEY - your API key for accessing 2GIS services.

  If you use separate keys for maps and search and for routing, specify them in the MAPGL_API_KEY and ROUTING_API_KEY variables, respectively.

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_API_KEY",
        "ROUTING_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Where:

• PATH_TO_REPO - path to the MCP server repository folder containing the built dist/index.js file.

• YOUR_API_KEY - your API key for accessing 2GIS services.

  If you use separate keys for maps and search and for routing, specify them in the MAPGL_API_KEY and ROUTING_API_KEY variables, respectively.

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_API_KEY",
        "ROUTING_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Where:

• PATH_TO_REPO - path to the MCP server repository folder containing the built dist/index.js file.

• YOUR_API_KEY - your API key for accessing 2GIS services.

  If you use separate keys for maps and search and for routing, specify them in the MAPGL_API_KEY and ROUTING_API_KEY variables, respectively.

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_API_KEY ROUTING_API_KEY=YOUR_API_KEY node dist/index.js

Where YOUR_API_KEY is your API key for accessing 2GIS services. If you use separate keys for maps and search and for routing, specify them in the MAPGL_API_KEY and ROUTING_API_KEY variables, respectively.