# @neariq/mcp-server

Connect NearIQ competitive intelligence to Claude Desktop, Claude Code, Cursor, Windsurf, and other Model Context Protocol clients.

- npm package: `@neariq/mcp-server`
- Source: https://github.com/NearIQ/mcp-server
- Docs: https://docs.neariq.io/guides/mcp-server
- Requires: Node.js 18+ and a NearIQ Growth+ API key

## What It Does

The NearIQ MCP server lets AI tools query your competitive intelligence through NearIQ's public v1 API. It exposes tools for your business profile, competitors, reviews, rank tracking, citations, AI visibility, market intelligence, content, alerts, reports, and AI chat.

The server runs locally over stdio. It does not store your API key; your MCP client passes the key through the `NEARIQ_API_KEY` environment variable at runtime.

## Install

Most MCP clients can run the package directly with `npx`, so you usually do not need a global install:

```bash
npx -y @neariq/mcp-server
```

If you want to test the package manually:

```bash
NEARIQ_API_KEY=niq_live_your_key_here npx -y @neariq/mcp-server
```

## Get A NearIQ API Key

1. Sign in to NearIQ.
2. Open [Settings > API Keys](https://app.neariq.io/settings?tab=api).
3. Create an API key with the scopes your MCP client should use.
4. Copy the key into your MCP client configuration as `NEARIQ_API_KEY`.

## Configure Your MCP Client

### Claude Desktop

Add this to `claude_desktop_config.json`:

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

### Claude Code

Add this to your `.mcp.json`:

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

### Cursor

Add this to `.cursor/mcp.json`:

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

### Windsurf

Add this to your Windsurf MCP settings:

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

## Environment Variables

| Variable | Required | Description |
| --- | --- | --- |
| `NEARIQ_API_KEY` | Yes | NearIQ API key, usually starting with `niq_live_`. |
| `NEARIQ_BASE_URL` | No | API base URL. Defaults to `https://app.neariq.io`. |

## Available Tools

| Tool | Description |
| --- | --- |
| `get_business_profile` | Your business profile, rating, and plan. |
| `get_business_details` | Address, phone, website, hours, and profile health. |
| `list_competitors` | Tracked competitors with health, momentum, and financial signals. |
| `get_competitor_detail` | Deep detail for one competitor. |
| `add_competitor` | Add a competitor by place ID or manual details. |
| `search_businesses` | Search businesses before adding a competitor. |
| `get_reviews` | Your reviews or a competitor's reviews. |
| `get_gap_analysis` | AI gap analysis against competitors. |
| `get_ai_visibility` | AI search visibility scores and recommendations. |
| `get_rank_checks` | Local search rank tracking results. |
| `get_citations` | NAP consistency and citation health. |
| `get_market_leaderboard` | Market leaderboard by rating, reviews, health, or velocity. |
| `generate_content` | Generate posts, FAQs, review templates, outlines, and more. |
| `list_content` | Previously generated content. |
| `get_alerts` | Business alerts and recommendations. |
| `get_behavioral_signals` | Engagement benchmarks and signal grades. |
| `generate_report` | AI intelligence report generation. |
| `list_reports` | Previously generated reports. |
| `ask_neariq` | Ask NearIQ AI about your business and market data. |
| `get_keyword_suggestions` | AI keyword suggestions for local SEO. |

## Example Prompts

```text
What are my top three competitors doing better than me?
```

```text
Generate a Google Business Profile post about our summer promotion.
```

```text
How visible is my business in AI search, and what should I fix first?
```

## Troubleshooting

### `NEARIQ_API_KEY environment variable is required`

Your MCP client did not pass the API key into the server process. Recheck the `env` block in your client configuration and restart the client.

### API 401 Or 403

Confirm the key is active, belongs to the right NearIQ workspace, and has the scopes required by the tool you are calling. API access requires a plan that includes NearIQ API usage.

### Tools Do Not Appear

Restart your MCP client after editing the configuration. If your client supports remote MCP servers, you can also use the hosted endpoint documented at https://docs.neariq.io/guides/mcp-server.

## Development

```bash
npm install
npm run build
```

The package source currently lives in the NearIQ monorepo and is mirrored to the public distribution repository.

## License

MIT