MCP server

The 2GIS MCP server provides AI agents with access to 2GIS geodata: maps, addresses, routes, and business information. It uses the open Model Context Protocol, routing requests from AI agents to the 2GIS API and returning results in a format suitable for processing. AI assistants use this data to answer user questions about places, addresses, businesses, and routes, as well as to analyze and visualize data.

How it works:

1. A user sends a request to an AI agent (for example, Find all 24-hour pharmacies).
2. The agent determines what geodata and services are needed (maps, POI search, etc.) and calls the MCP server.
3. The MCP server sends requests to the appropriate 2GIS APIs (for example, Static API for map images, Places API for searching and retrieving information about places).
4. The agent receives the result and generates a response for the user.

The MCP server provides access to the same data as direct API calls and is subject to the same pricing and rate limits.

Available tools and APIs

The MCP server provides the following tools:

Tool	Function	2GIS API used
search_poi	Searching for places and businesses by query and coordinates	Places API, Geocoder API
calculate_route	Building routes for various transport modes, calculating travel time and distance	Routing API
geocode	Forward 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 dashboard 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

1. Download and install Claude Desktop.

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

1. Download and install LM Studio.

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

1. Download and install Cursor.

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

1. Download and install VS Code.

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

Example

Images below show examples of the 2GIS MCP server used in a dialogue between the user and the AI assistant:

• Searching for objects by criteria:

  

• Displaying an object on the map:

  

• Calculating a route: