Skip to main content
Glama
README.md
# Rivalize MCP Server (`@rivalize/mcp`)

[![npm](https://img.shields.io/npm/v/@rivalize/mcp)](https://www.npmjs.com/package/@rivalize/mcp)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)

Give Claude, Cursor, Cline, or your own agent cited competitor intelligence as
JSON, over the Model Context Protocol.

**The Agent plan ($70 a year or $9 a month): API and MCP only, for your own AI.**
Rivalize collects; your own Claude, Cursor or agent does the thinking. No
dashboard and no AI analysis, so it costs a few dollars.

- **3 competitors at once, refreshed every 7 days**
- **Everything Rivalize collects about each, as JSON**, with sources and
  collection dates
- **Reads Rivalize's database of companies already collected**
  (`list_universe_companies`, `get_universe_company`)
- **500 API and MCP calls a day** (up to 250 an hour)

Get the Agent plan at [rivalize.ai/pricing](https://rivalize.ai/pricing?r=agmcp#agent). Developer and API
documentation: [rivalize.ai/developers](https://rivalize.ai/developers?r=agmcp).

## What it does

This server connects Claude, Cursor or any other MCP client to
[Rivalize](https://rivalize.ai/?r=agmcp). Your assistant can tear down a competitor's
positioning, pricing, ads, social presence, reviews, hiring and momentum in one
call, search the Rivalize universe of tracked companies, and read the projects,
reports, battlecards, timelines and evidence in your own Rivalize account.
Every answer comes from data Rivalize has collected, with dates and sources,
rather than from a model's memory.

The server is read-only by default. Three write tools, `add_competitor`,
`run_report` and `set_agent_competitor`, are available when you opt in with
`RIVALIZE_MCP_ALLOW_WRITES=1`. `run_report` starts a real report that uses your
credits, so it asks you to preview first and confirm.

## Quick start

Requires **Node.js 22 or newer** (`node --version`).

1. Choose a plan at [rivalize.ai/pricing](https://rivalize.ai/pricing?r=agmcp#agent): the **Agent** plan
   ($70 a year or $9 a month) is built for API and MCP use. A 14-day Growth
   trial is arranged with the Rivalize team; see the pricing page.
2. Create an API key under **Settings → API Keys** in the Rivalize app. Keys
   start with `rk_live_`. A key from any plan works, including the free plan,
   which gets rate-limited reads.
3. Add the server to your client using one of the blocks below.

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
or `%APPDATA%\Claude\claude_desktop_config.json` (Windows), then restart Claude
Desktop:

```json
{
  "mcpServers": {
    "rivalize": {
      "command": "npx",
      "args": ["-y", "@rivalize/mcp"],
      "env": { "RIVALIZE_API_KEY": "rk_live_..." }
    }
  }
}
```

### Claude Code

```bash
claude mcp add rivalize -e RIVALIZE_API_KEY=rk_live_... -- npx -y @rivalize/mcp
```

### Cursor

Add to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for all
projects:

```json
{
  "mcpServers": {
    "rivalize": {
      "command": "npx",
      "args": ["-y", "@rivalize/mcp"],
      "env": { "RIVALIZE_API_KEY": "rk_live_..." }
    }
  }
}
```

### Cline

In Cline, open the **MCP Servers** panel, choose **Configure**, then **Configure MCP Servers**. This opens `cline_mcp_settings.json`. Add:

```json
{
  "mcpServers": {
    "rivalize": {
      "command": "npx",
      "args": ["-y", "@rivalize/mcp"],
      "env": { "RIVALIZE_API_KEY": "rk_live_..." }
    }
  }
}
```

Save the file. The `rivalize` server appears with a green dot after about 10 to 15 seconds (the first start downloads the package). On Windows, if it does not start, use `"command": "cmd"` and `"args": ["/c", "npx", "-y", "@rivalize/mcp"]`.

If you ask Cline to install it for you, point it at [llms-install.md](./llms-install.md).

### Any MCP client (stdio)

The server speaks MCP over stdin and stdout. Configure your client to launch:

| Setting | Value |
|---------|-------|
| Command | `npx` |
| Arguments | `-y @rivalize/mcp` |
| Environment | `RIVALIZE_API_KEY=rk_live_...` |
| Transport | stdio |

On Windows, some clients cannot launch `npx` directly because it is `npx.cmd`.
Use `cmd` as the command and `/c npx -y @rivalize/mcp` as the arguments
instead.

## Plans and limits

| Plan | Price | Competitors | What is included for MCP and API |
|------|-------|-------------|----------------------------------|
| **Agent** | **$70/yr or $9/mo** | **3 at once**, refreshed every 7 days | **API and MCP only, for your own AI.** Everything Rivalize collects about each competitor as JSON, access to Rivalize's database of companies already collected, and **500 API and MCP calls a day** (250 an hour). One competitor change per slot per calendar month. No dashboard and no AI analysis. |
| **Starter** | $19/mo ($190/yr) | 3 | Web dashboard, Monday briefing, cited change alerts, plus API, MCP and webhooks. |
| **Growth** | $79/mo ($790/yr) | 10 | Everything in Starter with broader coverage, plus recommended actions on material changes. |
| **Pro** | $199/mo ($1,990/yr) | 25 | Everything in Growth plus cited sales battlecards (`get_battlecard`) and 1-year change history. |
| **Agency** | $599/mo ($5,990/yr) | 50 | Unlimited client workspaces, dashboard, battlecards, webhooks, plus API and MCP. |

Prices and limits are always current at [rivalize.ai/pricing](https://rivalize.ai/pricing?r=agmcp#agent).

## Tools

Sixteen read-only tools are always available: fourteen for dashboard plans and
two for Agent plans. The three write tools (`add_competitor`, `run_report` and
`set_agent_competitor`) are registered only when `RIVALIZE_MCP_ALLOW_WRITES` is
set to `1`, `true` or `yes`; without it, they do not exist for the client.

| Tool | Access | What it does | Key arguments |
|------|--------|--------------|---------------|
| `teardown_competitor` | read | One-call strategy teardown of a competitor as Markdown: positioning, pricing, ads, social, reviews, hiring, momentum and weaknesses to attack, with when the data was last refreshed | `domain` (required) |
| `list_universe_companies` | read | Search the Rivalize universe, the cross-customer dataset of tracked companies | `q`, `category` (slug), `layer`, `limit` (1-100), `offset` |
| `get_universe_company` | read | Full universe profile for one company: identity, pricing, features, ads, social, reviews, funding and hiring, rankings, signals, momentum | `domain` (required), `layers` |
| `list_projects` | read | The projects in your account; returns the `project_id` other tools take | none |
| `list_reports` | read | Your reports, newest first. Reading never generates a report | `project_id`, `limit` (1-100), `offset` |
| `get_report` | read | One report as Markdown, whole or one section or one competitor at a time | `report_id` (required), `section`, `competitor`, `page` |
| `list_competitors` | read | The competitors you track, with momentum score, its threat-level band and, where the API provides it, each rival's standing on your Brief | `project_id`, `limit` (1-100), `offset` |
| `get_competitor_intelligence` | read | Latest stored intelligence for one tracked competitor; a field is present only when it was measured | `competitor_id` (required) |
| `get_battlecard` | read | Cited sales battlecard for one tracked competitor. Requires a Pro plan | `competitor_id` (required) |
| `get_strategic_timeline` | read | Evidence-linked timeline of competitor moves across pricing, product, people, funding and content/social | `project_id` (required), `days` (`30`, `90`, `180`), `competitor_id`, `lanes`, `format`, `page` |
| `get_competitive_landscape` | read | Current or stored weekly positions of competitors by activity and strategic importance | `project_id` (required), `week` (`YYYY-MM-DD`), `format`, `page` |
| `get_freshness` | read | When each tracked competitor in a project was last actually observed, and how | `project_id` (required) |
| `get_evidence` | read | The sources behind the facts for your product or one competitor: URL, what it supports, and when it was read | `project_id` (required), `competitor_id` |
| `add_competitor` | **write**, opt-in | Add competitor URLs to a project. Spends credits and queues analysis | `project_id` (required), `urls` (1-10, required) |
| `run_report` | **write**, opt-in | **Starts a real report that uses your credits** (paid dashboard plans; about 10 to 20 minutes). Two steps: without `confirm` it starts nothing and returns a preview (depth, the project's competitors, the credits it will use, credits and monthly reports left, expected time). With `confirm: true` it starts the run. `depth` is `full` (15 credits per 5 competitors, uses a monthly report) or `quick` (1 credit per competitor). At most 3 runs a day through the API or MCP per account, and the same request within 10 minutes returns the run already started | `project_id` (required), `depth`, `confirm` |
| `get_report_status` | read | Whether a report started with `run_report` has finished (`processing`, `completed`, `no_competitors`, `no_rivals`), and the next call. Poll no more often than every 30 seconds | `report_id` (required) |
| `list_agent_competitors` | read | **Agent plans.** The 3 tracked-competitor slots: who is tracked, when each was last collected, when it refreshes next (every 7 days), and how many slot changes are left this calendar month | none |
| `get_agent_competitor` | read | **Agent plans.** The raw data collected about one tracked competitor, by group (`core`, `ads_seo`, `extended`), each module with its source and `collected_at`. A group your plan does not include is listed under `not_in_plan`. Your own assistant does the analysis | `competitor_id` (the domain, required), `group` |
| `set_agent_competitor` | **write**, opt-in | **Agent plans.** Put a competitor in a slot, or replace the one in a slot (`slot` 0-2). Uses no credits and queues a collection. Each slot can be replaced once per calendar month (the refusal gives the reset date); a fourth competitor at once is refused | `url` (required), `name`, `slot` |

Agent plans cannot run work that needs a model (battlecards, teardown prose,
reports): the API refuses those calls with an `agent_*` code and the tool shows
you the API's sentence unchanged. `run_report` and the dashboard reads are for
dashboard plans; the Free and Agent plans are refused by the API with
`PLAN_REQUIRED` or `agent_model_work_not_in_plan`.

`project_id` and `competitor_id` are UUIDs from `list_projects` and
`list_competitors`. Tools that read your account only ever see your own data.

### Report sections

`get_report` takes a `section` so your assistant can read the part a question
needs instead of the whole report:

| Section | Contains |
|---------|----------|
| `tldr`, `biggest-threat`, `blind-spots`, `actions` | The report's headline sections (`actions` is what your product should do) |
| `battlecards` | The cited sales battlecards |
| `competitors` | Every competitor's section in full |
| `pricing`, `momentum`, `app-store`, `strengths`, `weaknesses`, `key-findings`, `creators`, `ads`, `tech-stack` | One topic gathered from every competitor's section |

A report has only the sections it has data for; asking for any other name
returns an error that lists the sections it does have. `section` combines with
`competitor`, so `section: "pricing"` with `competitor: "Acme"` returns Acme's
pricing. A figure the report's fabrication check could not match to a source is
kept and marked `(not confirmed in the pages read)`; a name or citation the
check found to belong to another entity is taken out with its sentence, exactly
as in the report.

### Long responses

Every response stays under 25,000 characters, and nothing is cut silently:

- **Markdown** (`get_report`, `get_strategic_timeline`,
  `get_competitive_landscape`) is split into pages at section boundaries. Each
  page starts with `Page N of M`, how much remains, and the exact call for the
  next page.
- **Lists** (`list_universe_companies`, `list_competitors`, `list_reports`)
  return `pagination.next_offset`; continue from it until it is `null`.
- **Objects** (`get_universe_company`, and timeline or landscape JSON) cap long
  arrays and record the cap in `_capped`. A field that still does not fit is
  listed in `_omitted` with the call that fetches it.

## Example prompts

- "Tear down linear.app." (`teardown_competitor`)
- "Who are the players in AI developer tools?" (`list_universe_companies`)
- "Summarize my latest report, then show me what my competitors charge."
  (`list_reports`, `get_report` with `section: "pricing"`)
- "Which of my competitors moved most this quarter, and what did they do?"
  (`get_competitive_landscape`, `get_strategic_timeline`)
- "Give me sales talking points against my top competitor." (`list_competitors`,
  `get_battlecard`)
- "Where does that pricing claim come from, and how fresh is it?"
  (`get_evidence`, `get_freshness`)

## Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `RIVALIZE_API_KEY` | yes | none | Your Rivalize API key. Must start with `rk_live_`; the server exits at startup with a message if it is missing or malformed. |
| `RIVALIZE_API_URL` | no | `https://rivalize.ai` | Origin of the Rivalize API. A key only works on the server that issued it: leave this unset for rivalize.ai, and for a self-hosted or non-production Rivalize server set it to that server's origin, or every call returns 401. |
| `RIVALIZE_MCP_ALLOW_WRITES` | no | off | `1`, `true` or `yes` (any case) registers the write tools: `add_competitor` (spends credits, queues analysis), `run_report` (**starts a real report that uses your credits**; preview first, then `confirm: true`) and `set_agent_competitor` (Agent plans; no credits). Any other value, or unset, keeps the server read-only. |
| `HTTPS_PROXY` / `HTTP_PROXY` | no | none | Route requests through a corporate proxy. Lowercase forms are also read, and `HTTPS_PROXY` wins when both are set. `NO_PROXY` is honoured. Errors name the proxy host, never its credentials. |

## Troubleshooting

### "Connection closed"

When the server cannot start, many clients show only "Connection closed" or a
failed status. The server prints the reason as the first line of its stderr,
prefixed `rivalize-mcp:`, and most clients keep stderr in their MCP log. The
usual causes:

1. **`RIVALIZE_API_KEY` is missing or invalid.** The log reads
   `rivalize-mcp: RIVALIZE_API_KEY is required`, or says the key does not look
   like a Rivalize API key (it must start with `rk_live_`). Put the key in the
   server's `env` block and restart the client.
2. **Node.js is older than 22.** Run `node --version` and install Node.js 22 or
   newer. Your client uses whichever `node` and `npx` come first on its own
   `PATH`, which can differ from your terminal's.
3. **No network access.** `npx` downloads the package on first run, and every
   tool call goes to `https://rivalize.ai` (or `RIVALIZE_API_URL`). Behind a
   corporate proxy, set `HTTPS_PROXY`. A network error names the server and the
   cause code, such as `ECONNREFUSED` or `ENOTFOUND`.

To see the message directly, run the server in a terminal with the same key:

```bash
RIVALIZE_API_KEY=rk_live_... npx -y @rivalize/mcp
```

A healthy server prints `rivalize-mcp-server connected via stdio` to stderr
and waits for input (press Ctrl+C to stop). Anything else is the reason your
client could not connect.

### Every call returns 401

The key was rejected by the server it was sent to, and the error names that
server. Check that the key has not been revoked, and that `RIVALIZE_API_URL` is
unset unless the key was issued by a different Rivalize server.

### A tool says it needs a higher plan

Reads are available on every plan. Some capabilities, such as battlecards and
full timeline or landscape history, need a higher plan; the error says which
and links to [rivalize.ai/pricing](https://rivalize.ai/pricing?r=agmcp#agent).

## Docker

The repository includes a `Dockerfile` that builds the same stdio server on
Node 22 and runs it as a non-root user.

```bash
docker build -t rivalize-mcp .
```

```json
{
  "mcpServers": {
    "rivalize": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "RIVALIZE_API_KEY", "rivalize-mcp"],
      "env": { "RIVALIZE_API_KEY": "rk_live_..." }
    }
  }
}
```

Run the container with `-i` and without a TTY, since MCP uses stdin and
stdout. `-e RIVALIZE_API_KEY` with no value passes the key through from the
client's environment, so it never appears on the `docker run` command line.
Add `-e RIVALIZE_API_URL` or `-e RIVALIZE_MCP_ALLOW_WRITES` the same way if you
need them.

## Privacy Policy

This server is a thin client for the Rivalize API.

- **What it sends, and where.** Each tool call becomes an HTTPS request to the
  Rivalize API at `https://rivalize.ai`, or the origin you set in
  `RIVALIZE_API_URL`. A request carries your API key as a Bearer token, a
  `User-Agent` of `rivalize-mcp/<version>`, and the tool's arguments: for
  example a company domain, a search term, a project, report or competitor id,
  and, with writes enabled, the competitor URLs you add. If you set
  `HTTPS_PROXY` or `HTTP_PROXY`, requests go through that proxy. Nothing is
  sent anywhere else.
- **What it does not send.** No telemetry, analytics or crash reports. It does
  not read files on your machine, your conversation, or other tools' output;
  it sees only the arguments your MCP client passes to its own tools.
- **What it stores locally.** Nothing. It writes no files, keeps no cache and
  holds no state between runs. Your key lives in your MCP client's
  configuration, not in this server. Diagnostic messages go to stderr, which
  your MCP client may log; they never include your API key.
- **What Rivalize does with requests.** The API processes them under the
  Rivalize Privacy Policy at [rivalize.ai/privacy](https://rivalize.ai/privacy).
  Rivalize is operated by Downshift LLC, the data controller for that data.
  Privacy questions go to privacy@rivalize.ai.

## Security

Please report vulnerabilities privately to **support@rivalize.ai** with
"security" in the subject line, not in a public issue. Include the package
version (`npm view @rivalize/mcp version`, or the `User-Agent` above), what you
did, and what happened. We will acknowledge your report and keep you updated
until it is resolved.

Treat your API key as a credential. Keep it in your client's `env` block or
your shell environment, never in a shared or committed file, and revoke a
leaked key under **Settings → API Keys**.

## Contributing

Bug reports and feature requests are welcome at
[github.com/Downshift/rivalize-mcp/issues](https://github.com/Downshift/rivalize-mcp/issues).
For account and billing questions, email support@rivalize.ai.

To work on the server locally:

```bash
npm ci
npm run typecheck
npm run build      # emits dist/, which the rivalize-mcp bin runs
npm test           # offline: every API call is mocked or served by a local fixture
```

`server.json` is the [MCP Registry](https://registry.modelcontextprotocol.io)
entry. The tests validate it against the official schema (vendored in
`schema/`) and check that its name, version and package match `package.json`.

## Changelog

### 0.5.1

- README, `llms-install.md`, directory listings and `server.json` now lead
  with the Agent plan ($70 a year or $9 a month: 3 competitors at once,
  refreshed every 7 days, everything collected as JSON, access to the
  universe of already-collected companies, 500 API and MCP calls a day).
  No change to the tools.

### 0.5.0

- New `run_report`, a write tool (opt-in with `RIVALIZE_MCP_ALLOW_WRITES=1`).
  It **starts a real report that uses your credits**, so it works in two
  steps: without `confirm` it starts nothing and returns a preview of the
  depth, competitors, credits it will use and what you have left; with
  `confirm: true` it starts the run. The API limits runs to 3 a day per account
  and returns the run already started for the same request within 10 minutes.
- New `get_report_status` to check whether a started report has finished.
- `get_report` now reports figures the fabrication check could not match to a
  source as `(not confirmed in the pages read)` instead of removing them.

### 0.4.0

- Agent plan tools: `list_agent_competitors` and `get_agent_competitor` (reads)
  and `set_agent_competitor` (a write, opt-in) for the three tracked-competitor
  slots of an Agent plan.
- Every tool result is marked as AI-generated: a top-level `ai_generated` and
  `ai_disclosure` in JSON results, a closing disclosure line on Markdown
  results, and `_meta.ai_generated` on all of them. Errors are left unchanged.

### 0.3.2

- `list_competitors` now tells your assistant how to pick a top competitor:
  by the rival's standing on your Brief (`brief.standing`) when the API returns
  it, otherwise by `momentum_score`. `threat_level` is described as what it is,
  the band of the momentum score, and is no longer offered as a ranking.
- When a row's standing is still being read (`brief.state` is `deferred`),
  `list_competitors` asks for the same page again, up to 4 times, 1.5 seconds
  apart. Against an API that returns no `brief`, it makes one request per call
  as before.
- Clearer wording in the 401 hint for a self-hosted or non-production Rivalize
  server, and in the `add_competitor` description.

### 0.3.1

- The version this repository's history starts from: thirteen read-only
  tools, the opt-in `add_competitor` write tool, responses kept under 25,000
  characters with explicit paging, proxy support, and the MCP Registry entry in
  `server.json`.

## License

MIT, © 2026 Downshift LLC. See [LICENSE](./LICENSE).

TDQS

A4.2/5.0

Scored across 16 tools

Disambiguation4/5

Descriptions are unusually explicit and cross-reference each other (e.g. list_competitors vs list_agent_competitors, get_competitor_intelligence vs get_universe_company vs teardown_competitor), so an agent has strong guidance. However there is genuine surface overlap: two competitor-listing tools split by plan, and several tools that all return competitor info could still be misselected when the agent's plan/report state is unknown.

Naming Consistency4/5

Nearly all tools follow a clean snake_case get_/list_ verb_noun pattern (list_projects, get_report, get_freshness, get_competitive_landscape). Minor deviations like teardown_competitor (verb without a get_/list_ prefix) and the abstract get_freshness keep it from being perfect.

Tool Count4/5

16 tools is at the upper edge but justified by the multi-tier design (own account, Agent-plan raw data, cross-customer universe, reports, battlecards). Each group maps to a distinct capability, so the count is reasonable rather than inflated.

Completeness3/5

The surface is read-heavy: get_report_status explicitly references a run_report to start reports, yet no such tool exists, so generation is a dead end. There is also no tool to add/remove/track competitors or create projects, leaving notable gaps in the lifecycle even though read/coverage is rich.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues