Dimensions Analytics MCP

The Dimensions Analytics MCP server connects AI assistants — such as Claude Desktop, Cursor, VS Code (Copilot), and Windsurf — to Dimensions research data through the Model Context Protocol (MCP).

Once configured, you can ask your assistant — in plain language — to:

  • Search publications, grants, researchers, and other record types

  • Run analytics, facets, and trend queries

  • Look up records by DOI or Dimensions ID

  • Explore the live Dimensions schema

For example: “Find the 20 most-cited publications on CRISPR gene editing since 2020.”

Note

Subscription required

The Dimensions Analytics API is subscription-only, so your Dimensions account must be activated for this service. MCP access is available to API subscribers, subject to the same reasonable use terms. Email supportapi@dimensions.ai with any questions.

Prerequisites

Before you start, make sure you have:

  • Node.js 20 or later — required for the local server. Check your version with node --version. If it’s missing or older than 20, install it from nodejs.org (the guided installer can also help you do this).

  • A Dimensions API key — the same key used for the Dimensions DSL API. Find or generate your key in Dimensions. See Getting an API Key for instructions.

  • An MCP-compatible client — for example Claude Desktop, Cursor, VS Code (Copilot), or Windsurf. Any client that supports the Model Context Protocol will work; the guided installer can auto-configure the four listed here, and you can set up others manually.

Don’t have an API key yet? Request a demo or quote here.

Note

Keep your API key private

Treat your API key like a password. MCP config files store it in plain text and are not encrypted — never commit them to a public repository or share them.

Quick install

The guided installer checks Node.js, downloads the server from npm, asks for your API key, and configures your chosen apps — Claude Desktop, Cursor, VS Code (Copilot), or Windsurf. It installs to ~/.dimensions-analytics-mcp, backs up any existing config before changing it, and needs no repository clone or GitHub token.

Mac / Linux — paste in Terminal:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/digital-science/dimensions-analytics-mcp/main/scripts/install.sh)"

Note

Copy the command exactly as shown.

Don’t rewrite it as curl … | bash — the installer won’t be able to ask you questions that way.

Windows — paste in PowerShell:

irm https://raw.githubusercontent.com/digital-science/dimensions-analytics-mcp/main/scripts/install.ps1 | iex

When it finishes, quit and reopen each configured app.

Using a different MCP client, or want advanced options? Any MCP-compatible client works — see Manual setup below to configure one yourself, or the MCP installation guide for non-interactive install and developer options.

Verify the installation

After restarting your app, look for dimensions in its MCP or connectors settings — it should show as connected. Then test it with a prompt:

“List the available Dimensions tools.”

If the assistant responds with Dimensions tools (such as search_publications or describe_schema), you’re ready to go. If not, see Troubleshooting.

Manual setup

If you prefer to configure the server yourself, add an entry to your MCP client’s config file. This example uses npx, so no global install is required:

{
  "mcpServers": {
    "dimensions": {
      "command": "npx",
      "args": ["-y", "@digital-science-dsl/dimensions-analytics-mcp"],
      "env": {
        "DIMENSIONS_API_KEY": "your-api-key"
      }
    }
  }
}

Note

VS Code (Copilot MCP) uses the key servers instead of mcpServers. Otherwise the structure is the same.

Config file locations

The table below covers common clients. For any other MCP-compatible client, add the same dimensions entry to that client’s MCP config file — check its documentation for the exact location and whether it uses the mcpServers or servers key.

Client

Config file

Cursor

~/.cursor/mcp.json or .cursor/mcp.json

Claude Desktop (macOS)

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

Claude Desktop (Windows)

%APPDATA%\\Claude\\claude_desktop_config.json

VS Code (Copilot MCP)

~/.vscode/mcp.json

Windsurf

~/.codeium/windsurf/mcp_config.json

After editing the config, quit and reopen the app, then follow Verify the installation above.

Using Dimensions in chat

Once the server is connected, just ask your assistant in plain language. Example prompts:

  • “Find the 20 most-cited publications on CRISPR gene editing since 2020.”

  • “Search NIH grants about cancer immunotherapy started after 2020.”

  • “Who are the top researchers working on quantum computing?”

  • “Look up DOI 10.1038/nature12373 and show title, citations, and journal.”

  • “Citation trend for large language model publications from 2018 to 2024.”

A few tips for better results:

  • Be specific about scope — a year range, number of results, or source (“since 2020,” “top 20,” “NIH grants”) gets you a sharper answer.

  • Refine with follow-ups — the assistant keeps context, so you can narrow or expand a result instead of rewriting your question from scratch.

  • Write DSL directly if you prefer — for advanced boolean queries or NLP functions, you can ask in DSL and the assistant will run it.

A full tool reference, example arguments, and routing notes are in the MCP usage guide.

Note

Rate limits

Usage is subject to rate limits. If queries start failing or getting throttled, you may be sending requests too quickly — see the reasonable use guidelines for the current limits.

Troubleshooting

Symptom

Likely cause

What to do

dimensions doesn’t appear in your app after restarting

Config file in the wrong location, or invalid JSON

Confirm the path against the config file locations table, and validate the JSON (a trailing comma or missing brace will silently break it).

Your app has no MCP / connectors settings at all

Client version is too old to support MCP

Update the app to the latest version, then restart it.

node: command not found or a Node version error

Node.js not installed, too old, or not on your PATH

Run node --version. If it’s missing or below 20, install from nodejs.org, then restart your terminal and app.

Authentication error / 403 / “unauthorized”

API key is wrong, or your account isn’t activated for the Analytics API

Re-check the key in your config (no extra spaces or quotes). Verify in Dimensions that your account has API access. If it should and doesn’t work, email supportapi@dimensions.ai.

Server is listed but tools don’t respond

Stale npx cache, or first-run download still in progress

Wait a few seconds and retry. If it persists, run npx clear-npx-cache (or npm cache clean --force) and restart the app.

Queries fail intermittently with rate-limit errors

You’re sending requests too quickly

Slow down or batch requests. See the reasonable use guidelines.

Installer can’t read your input

The install command was piped to bash

Use the bash -c "$(curl …)" form shown in Quick install, not curl … | bash.

Still stuck? Email supportapi@dimensions.ai with your client name and version, your OS, the output of node --version, and the error message you’re seeing.

Updating and uninstalling

Updating

  • Installed via the guided installer: the installer pins a fixed version in ~/.dimensions-analytics-mcp, so it won’t update on its own. Re-run the install command to reinstall the current published version.

  • Configured manually with ``npx``: each launch fetches the latest version automatically. To force a refresh, run npx clear-npx-cache and restart your app.

Uninstalling

  1. Remove the dimensions entry from each app’s config file (see config file locations).

  2. If you used the guided installer, also delete its install directory: ~/.dimensions-analytics-mcp.

  3. Restart each app.

Further documentation

The MCP server repository includes full reference documentation:

  • Installation — guided installer, manual setup, non-interactive install, and build from source.

  • Usage guide — workflows, the full tool reference, and example prompts. Start here if you want to get the most out of the available tools.

  • Reference — environment variables, rate limits, and schema cache behaviour.

  • Field aliases — field-name shortcuts accepted by the search tools.

Package: @digital-science-dsl/dimensions-analytics-mcp on npm.