Quick Start

First steps to experiment Woosmap MCP Server

Introduction

The Woosmap MCP Server enables you to plug location intelligence directly into your Large Language Models (LLMs). It is designed to help you easily integrate powerful geocoding, search, and mapping capabilities into AI assistants like Claude, ChatGPT, etc. Let’s go through integrating with Claude as an example.

Prerequisites

As for any Woosmap services, you need to make sure to get proper credentials to use and secure those services. If you do not have a Woosmap Organisation of your own yet, please follow the Get Started steps first.

Once onboarded:

  • Create a dedicated Project for your MCP usages via the Woosmap Console.
  • Activate the required Products for this Project (e.g Localities, Map, Stores)
  • Create a dedicated secured Private API Key.
  • Load your own Assets (stores, restaurants, etc) if you want to personalize the experience See the Store Data Management API for more details.
  • Install an MCP-compatible client, such as the Claude Desktop App.

Private API keys are credentials, guard them closely and do not share them with anyone who doesn’t explicitly need access. Ensure any proper restictions are applied where possible.

Claude Desktop Setup

Follow these steps to plug Woosmap into Claude Desktop and enpower it with real world location intelligence.

Step 1: Locate the Configuration File

Open your terminal or file explorer and navigate to the config file for your operating system. If the file does not exist, create it.

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Step 2: Add the Configuration

Open the file in a text editor and add the following JSON configuration.

Important: Replace PRIVATE_KEY with your actual Woosmap Private API Key.

JSON
        {
  "mcpServers": {
   "woosmap remote mcp server": {
     "command": "npx",
     "args": [
     "mcp-remote",
     "https://api.woosmap.com/mcp",
     "--header",
     "X-Api-Key: PRIVATE_KEY"
    ]
   }
  }
}

Step 3: Enable Developer Mode (Optional)

Edit or create developer_settings.json in the same folder as the config file above. Add the following JSON configuration to it.

JSON
        {
 "allowDevTools": true
}

Step 4: Restart Claude

Completely close and restart the Claude Desktop application in order to apply all modifications done in the configuartion files.

Check the Installation

To verify that the server is working, open a new chat in Claude and ask:

“What location tools do you have available via Woosmap?”

Claude should list the tools (geocode, find_nearby, etc.) defined in the first section. You can then try a prompt like:

“Find the nearest coffee shop to the Eiffel Tower and show me a map of it.”

Troubleshouting

If the Woosmap server does not appear in Claude or tools fail to run, check these common issues.

Server Not Connected

  • Restart Claude: You must completely quit and restart the Claude Desktop app after editing the config file.
  • Check Node.js Installation: Ensure Node.js and npx are installed (node -v in your terminal). Windows Users: If you see an error like exec: “npx”: executable file not found, try providing the full path to npx in your config file (e.g., C:\Program Files\nodejs\npx.cmd).
  • JSON Syntax: Ensure your claude_desktop_config.json is valid JSON (no missing commas or unescaped backslashes in Windows paths).

Authentication Errors (401/403)

  • Invalid API Key: Double-check that you replaced PRIVATE_KEY with your actual key string in the config file.
  • Wrong Key Type: You must use a Private API Key (starts with private_…). Public keys (used for frontend widgets) will not work here.
  • IP Restrictions: If your Private Key has IP restrictions, ensure your current machine’s IP is allowed, or temporarily disable restrictions to test.
Was this helpful?