> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neariq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect NearIQ to compatible AI tools via the Model Context Protocol.

## What is MCP?

The Model Context Protocol lets AI tools call external APIs as tools during a conversation. NearIQ supports two MCP connection modes:

* Hosted Streamable HTTP endpoint at `https://app.neariq.io/api/mcp` for clients that support remote MCP servers.
* Local stdio package via `npx @neariq/mcp-server` for clients that run local MCP servers.

## Prerequisites

* A NearIQ account on the Growth plan or above.
* A NearIQ API key from [Settings > API Keys](https://app.neariq.io/settings?tab=api).
* Node.js 18+ only if you use the local npm package.

## Hosted endpoint

Use this when your AI tool supports remote MCP servers or Streamable HTTP:

```json theme={null}
{
  "mcpServers": {
    "neariq": {
      "url": "https://app.neariq.io/api/mcp",
      "headers": {
        "Authorization": "Bearer niq_live_your_key_here"
      }
    }
  }
}
```

Hosted endpoint tools are read-only in the first release:

| Tool                     | Description                                                                                           |
| ------------------------ | ----------------------------------------------------------------------------------------------------- |
| `list_competitors`       | Tracked competitors with rating, review count, health, momentum, and financial signals                |
| `get_business_overview`  | Business profile, category, contact fields, coordinates, and place ID                                 |
| `get_rankings`           | Local search rank checks, average rank, top-3 percentage, and grid results                            |
| `get_reviews_summary`    | Cached competitor reviews, rating distribution, sentiment, and response-rate context                  |
| `get_ai_visibility`      | AI search mention rates per engine, average position, top queries, and recommendations                |
| `get_gap_analysis`       | Latest competitive gap analysis — where you lead and where competitors are ahead                      |
| `get_citations`          | Directory citation listings, name/address/phone/website match, and a citation health score            |
| `list_content`           | Content Studio drafts (GBP posts, social posts, FAQs, landing copy, blog outlines), newest first      |
| `get_market`             | Market trends, keyword/theme mention counts, sentiment, gaps, and area-wide benchmarks                |
| `get_hiring_signals`     | Verified local competitor job postings with a derived hiring signal (quiet, watch, hiring, expanding) |
| `get_behavioral_signals` | Your engagement report card vs competitors, with per-signal grades and an overall score               |
| `get_brand_mentions`     | Recent web mentions of your brand with source, snippet, URL, and sentiment                            |
| `get_alerts`             | Recent alerts (rating drops, new competitors, review spikes) with severity and recommendations        |
| `get_reports`            | Intelligence reports with their lenses, date, and export state                                        |
| `get_my_reviews`         | Your own Google reviews with rating distribution, response rate/speed, sentiment, and summary         |
| `get_leaderboard`        | Ranked leaderboard of businesses in a market by rating, reviews, health score, or review velocity     |

The hosted endpoint uses the same Growth+ API access, API-key scopes, org permissions, plan gates, and rate limits as the public REST API.

## Local package

Use the local package when your AI tool only supports stdio MCP servers:

```json theme={null}
{
  "mcpServers": {
    "neariq": {
      "command": "npx",
      "args": ["-y", "@neariq/mcp-server"],
      "env": {
        "NEARIQ_API_KEY": "niq_live_your_key_here"
      }
    }
  }
}
```

Optional environment variable:

| Variable          | Required | Description                                   |
| ----------------- | -------- | --------------------------------------------- |
| `NEARIQ_API_KEY`  | Yes      | Your NearIQ API key                           |
| `NEARIQ_BASE_URL` | No       | API base URL, default `https://app.neariq.io` |

The local package exposes the broader API-backed tool set for competitors, reviews, rankings, AI visibility, content, reports, alerts, market data, and chat.

## Troubleshooting

**Invalid or missing API key**
Confirm the key starts with `niq_live_` and is passed as `Authorization: Bearer ...` for the hosted endpoint or `NEARIQ_API_KEY` for the local package.

**API 403**
Your plan or API-key scopes do not allow the requested tool. Create a key with the required read scopes or upgrade to a plan with API access.

**Tools not appearing**
Restart your AI tool after saving the MCP config. For the hosted endpoint, confirm your client supports remote MCP servers.