The PinMeTo MCP Server enables seamless integration between the PinMeTo platform and AI agents such as Claude LLM, allowing users to interact with their location data and business insights through natural language. This server exposes a suite of tools that let you retrieve, analyze, and summarize data from PinMeTo, through multiple sources—including Google, Facebook, and Apple—covering metrics such as impressions, clicks, ratings, and more.

The MCP Server can be installed with one click in Claude Desktop, VS Code, or Cursor using the badges above. Manual installation instructions are also available below.

The single-click installer binary for Claude Desktop is available in the "Releases" tab:

https://github.com/PinMeTo/pinmeto-location-mcp/releases

Below are instructions on how to generate the binary with npx:

• npm
• npx (included with npm)
• Claude Desktop

1. Clone the repository:

   git clone https://github.com/PinMeTo/pinmeto-location-mcp.git

2. Open your project folder in your text editor.

   cd pinmeto-location-mcp

3. Build and Run the MCPB installer:

   npm install
   npm run build
   npx @anthropic-ai/mcpb pack

   • This generates a .mcpb file in your project directory.

4. Install in Claude Desktop:

   • With Claude Desktop open, double-click the .mcpb file.
   • Enter your PinMeTo API credentials when prompted (PinMeTo Account Settings).

• Enable the connector in Claude. You can now use the PinMeTo MCP integration.

Below are instructions on how to manually integrate the PinMeTo MCP with Claude Desktop:

• Node.js v22+ (recommended: NVM)
• npm (included with Node.js)
• Claude Desktop

1. Clone the repository:

   git clone https://github.com/PinMeTo/pinmeto-location-mcp.git

2. Open your project folder in your text editor.

   cd pinmeto-location-mcp

3. Install dependencies and build the project:

   npm install
   npm run build

4. Configure Claude Desktop:

   • Open your claude_desktop_config.json file. You can go to Preferences → Developer → Edit Config in the Claude Desktop Client. Or use on Mac:

   code ~/Library/Application\ Support/Claude/claude_desktop_config.json

   • Add the following MCP server configuration (with node)

     {
     "mcpServers": {
         "PinMeTo": {
         "command": "/absolute/path/to/node",
         "args": ["/absolute/path/to/project/build/index.js"],
         "env": {
             "PINMETO_API_URL": "",
             "PINMETO_ACCOUNT_ID": "",
             "PINMETO_APP_ID": "",
             "PINMETO_APP_SECRET": ""
         }
         }
     }
     }

   • Add the following MCP server configuration (with npx)

     {
     "mcpServers": {
         "PinMeTo": {
             "command": "npx",
             "args": ["-y", "PinMeTo/pinmeto-location-mcp"],
             "env": {
                 "PINMETO_ACCOUNT_ID": "",
                 "PINMETO_APP_ID": "",
                 "PINMETO_APP_SECRET": ""
             }
         }
     }
     
     }
     

   • Use absolute paths for both Node and your project:

   • Node path: which node

   • Project path: pwd

5. Get your PinMeTo API credentials:

   • Visit PinMeTo Account Settings and fill in the environment variables above.

6. Restart Claude Desktop:

   • Ensure all permissions are granted. You should now see "PinMeTo MCP" in your MCP selection.

All tools use the pinmeto_ prefix following MCP best practices.

• pinmeto_get_location - Get PinMeTo data for a SINGLE location by store ID
• pinmeto_get_locations - Get ALL location data with pagination, filtering, and caching
• pinmeto_search_locations - Search ALL locations for quick discovery

• pinmeto_get_google_insights - Get Google insights (all locations, or single if storeId provided)
• pinmeto_get_google_ratings - Get Google rating aggregates: averageRating, totalReviews, distribution (all locations, or single if storeId provided)
• pinmeto_get_google_reviews - Get Google reviews with pagination and filtering for sentiment analysis
• pinmeto_get_google_keywords - Get Google keywords (all locations, or single if storeId provided)

• pinmeto_get_facebook_insights - Get Facebook insights (all locations, or single if storeId provided)
• pinmeto_get_facebook_brandpage_insights - Get Facebook brandpage insights for ALL pages
• pinmeto_get_facebook_ratings - Get Facebook ratings (all locations, or single if storeId provided)

• pinmeto_get_apple_insights - Get Apple insights (all locations, or single if storeId provided)

All insights tools (Google, Facebook, and Apple) support time aggregation to significantly reduce token usage. By default, all insights are aggregated to a single total value, providing maximum token efficiency. You can optionally request different aggregation periods for more granular analysis.

• Total (default): Single aggregated value - maximum token reduction
• Daily: Full granularity, no aggregation
• Weekly: ~85% token reduction (7 days → 1 data point)
• Monthly: ~96% token reduction (30 days → 1 data point)
• Quarterly: ~98% token reduction (90 days → 1 data point)
• Half-yearly: ~99% token reduction (180 days → 1 data point)
• Yearly: ~99.7% token reduction (365 days → 1 data point)

The aggregation parameter is optional and defaults to "total":

{
  "storeId": "1337",
  "from": "2024-01-01",
  "to": "2024-12-31"
}

Returns a single total value by default (maximum token reduction)

To get different time periods, specify the aggregation parameter:

{
  "storeId": "1337",
  "from": "2024-01-01",
  "to": "2024-12-31",
  "aggregation": "monthly"
}

Get total metrics (default behavior):

// Returns a single aggregated value
{
  "from": "2024-01-01",
  "to": "2024-12-31"
}

Get yearly trends (monthly aggregation):

// Returns 12 data points instead of 365
{
  "storeId": "1337",
  "from": "2024-01-01",
  "to": "2024-12-31",
  "aggregation": "monthly"
}

Get quarterly business review:

// Returns 4 data points for the year
{
  "from": "2024-01-01",
  "to": "2024-12-31",
  "aggregation": "quarterly"
}

Get daily data (full granularity):

// Returns 365 individual data points
{
  "from": "2024-01-01",
  "to": "2024-12-31",
  "aggregation": "daily"
}

Time aggregation works with all insights tools:

• Google: pinmeto_get_google_insights
• Facebook: pinmeto_get_facebook_insights, pinmeto_get_facebook_brandpage_insights
• Apple: pinmeto_get_apple_insights

1. The MCP server fetches daily metrics from the PinMeTo API
2. Metrics are grouped by the specified time period (week, month, etc.)
3. Values are summed within each period
4. Aggregated data is returned in the same format as daily data

This client-side aggregation ensures compatibility with the PinMeTo API while dramatically reducing token consumption for AI interactions.

All insights tools support period comparison to analyze trends over time. Compare current metrics against previous periods or the same period last year.

Add the compare_with parameter to any insights request:

{
  "storeId": "1337",
  "from": "2024-01-01",
  "to": "2024-01-31",
  "compare_with": "prior_year"
}

When comparison is enabled, each metric includes additional fields:

{
  "insights": [
    {
      "metric": "views",
      "value": 1500,
      "priorValue": 1200,
      "delta": 300,
      "deltaPercent": 25
    }
  ],
  "periodRange": { "from": "2024-01-01", "to": "2024-01-31" },
  "priorPeriodRange": { "from": "2023-01-01", "to": "2023-01-31" },
  "timeAggregation": "total",
  "compareWith": "prior_year"
}

Year-over-Year comparison:

{
  "from": "2024-01-01",
  "to": "2024-01-31",
  "compare_with": "prior_year"
}

Month-over-Month with monthly aggregation:

{
  "from": "2024-01-01",
  "to": "2024-12-31",
  "aggregation": "monthly",
  "compare_with": "prior_period"
}

Period comparison works with all insights tools:

• Google: pinmeto_get_google_insights
• Facebook: pinmeto_get_facebook_insights, pinmeto_get_facebook_brandpage_insights
• Apple: pinmeto_get_apple_insights