npm package: @kineviz/graphxr-mcp
Description: MCP server for GraphXR - enables Claude/Cursor to create graph visualizations
Author: Kineviz
Latest version: 0.12.7

# @kineviz/graphxr-mcp

> **ALPHA SOFTWARE - EXPERIMENTAL**
>
> This MCP server is in early alpha stage. APIs may change without notice. Do not use in production environments. Use at your own risk.

MCP (Model Context Protocol) server for [GraphXR](https://graphxr.kineviz.com) - enables Claude and Cursor to create graph visualizations programmatically.

## Features

- Create and manage GraphXR projects
- Manage Grovebook notebooks (list, download, upload, rename, delete)
- Upload files (CSV, JSON, images) to projects
- Fetch OpenAPI spec and GraphXR API reference
- Execute JavaScript via the `gxr` API, take screenshots, and export graph data through a Playwright browser session

## Prerequisites

- Node.js 18 or later
- A GraphXR account with an API key
- Playwright Chromium browser (for browser tools; run `npx playwright install chromium`)

## Quick Start

### 1. Get Your API Key

1. Log in to GraphXR
2. Click your profile icon in the top right
3. Select "API Key" from the dropdown
4. Copy your API key

### 2. Install Playwright Browser

```bash
npx playwright install chromium
```

### 3. Configure Your MCP Client

#### Cursor IDE

Create or edit `.cursor/mcp.json` in your project or home directory:

```json
{
  "mcpServers": {
    "graphxr": {
      "command": "npx",
      "args": ["-y", "@kineviz/graphxr-mcp@latest", "graphxr-mcp"],
      "env": {
        "GRAPHXR_API_KEY": "your-api-key-here",
        "GRAPHXR_URL": "https://graphxr.kineviz.com",
      }
    }
  }
}
```

#### Claude Desktop

Add to your Claude Desktop configuration (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "graphxr": {
      "command": "npx",
      "args": ["-y", "@kineviz/graphxr-mcp@latest", "graphxr-mcp"],
      "env": {
        "GRAPHXR_API_KEY": "your-api-key-here",
        "GRAPHXR_URL": "https://graphxr.kineviz.com"
      }
    }
  }
}
```

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GRAPHXR_API_KEY` | Yes | - | Your GraphXR API key |
| `GRAPHXR_URL` | No | `http://localhost:9000` | GraphXR server URL |
| `ENABLE_BROWSER_USE` | No | `true` | Enable browser-dependent tools (`open_project`, `run_javascript`, `screenshot`, `export_graph`, `close_project`, `close_all_projects`). Requires Playwright Chromium. Set to `false` to disable browser tools. |
| `GRAPHXR_VIEWPORT_WIDTH` | No | `1280` | Browser viewport width in pixels |
| `GRAPHXR_VIEWPORT_HEIGHT` | No | `720` | Browser viewport height in pixels |
| `GRAPHXR_HEADLESS` | No | `false` | Run browser in headless mode (set to `true` for headless operation). Headed mode (default) is recommended for better visibility and debugging. Only relevant when `ENABLE_BROWSER_USE=true`. |
| `DEBUG` or `GRAPHXR_DEBUG` | No | `false` | Enable debug logging |

## Available Tools

### Always available

- **list_projects** - List all your GraphXR projects
- **create_project** - Create a new project
- **grove_list** - List grovebook files and folders in a project
- **grove_download** - Download a grovebook as markdown (Grove &ge; 2.0: raw markdown; older: JSON converted to markdown)
- **grove_upload** - Upload markdown as a grovebook (Grove &ge; 2.0: raw markdown; older: markdown converted to Grove JSON)
- **grove_delete_file**, **grove_rename_file**, **grove_create_folder**, **grove_delete_folder** - Grove file/folder operations
- **fetch_openapi_spec** - Fetch the OpenAPI specification from the GraphXR instance for discovering REST API endpoints and schemas
- **fetch_graphxr_api_reference** - Fetch the GraphXR JavaScript API reference documentation for generating code that uses the GraphXR API
- **upload_file** - Upload a local file (CSV, JSON, images, etc.) to a project

### Browser tools (disable with `ENABLE_BROWSER_USE=false`)

These tools launch a Playwright Chromium browser to interact with the GraphXR canvas. Multiple projects can be open simultaneously.

- **open_project** - Open a project in the browser session (supports `headless` toggle)
- **run_javascript** - Execute JavaScript code using the `gxr` API (requires `projectId`)
- **screenshot** - Take a screenshot of the current graph (requires `projectId`)
- **export_graph** - Export graph data as JSON, GraphXR, or CSV (requires `projectId`)
- **close_project** - Close a specific project's browser session (requires `projectId`)
- **close_all_projects** - Close all open browser sessions

### Grovebook download and upload (version behavior)

- **Grove &ge; 2.0.0**: The server stores Grove and markdown files natively. Download returns content as-is when the server sends markdown; upload sends your markdown directly with no conversion.
- **Grove &lt; 2.0.0**: Legacy behavior. Download converts Grove JSON to markdown (code blocks, headers, paragraphs). Upload converts markdown back to Grove JSON before sending.

The server’s Grove version is read from `GET /api/tempModule/tempModules` (module named `Grove`). If missing, version is treated as `1.0.0`.

## Example Usage

Ask Claude or Cursor:

> "Create a new GraphXR project called 'My Network' and add some sample nodes"

> "Take a screenshot of the current graph"

> "Run this JavaScript to create 5 connected nodes"

## Troubleshooting

### "Playwright browser not found"

Run `npx playwright install chromium` to install the required browser.

### "API key invalid"

1. Verify your API key is correct
2. Check that your GraphXR account is active
3. Ensure the `GRAPHXR_URL` matches your GraphXR server

### "Connection refused"

1. Check your internet connection
2. Verify the `GRAPHXR_URL` is accessible
3. Check if GraphXR is experiencing downtime

### Debug Mode

Enable debug logging to see detailed output:

```json
{
  "env": {
    "GRAPHXR_DEBUG": "true"
  }
}
```

You can also use `DEBUG=true` which works the same way.

## Using the local dev build with Claude

To use your locally built version of the MCP with Claude Desktop (or another MCP client) instead of the published npm package:

1. **Build the project** (from the repo root):

   ```bash
   yarn build
   # or: npm run build
   ```

   This produces `dist/index.js` (or the path shown in the build output).

2. **Point Claude at the local server.** In your Claude Desktop MCP config, use `node` with the path to the built script instead of `npx -y @kineviz/graphxr-mcp@latest`.

   **macOS (Claude Desktop)** — edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

   ```json
   {
     "mcpServers": {
       "graphxr": {
         "command": "node",
         "args": ["/absolute/path/to/graphxr-mcp/dist/index.js", "graphxr-mcp"],
         "env": {
           "GRAPHXR_API_KEY": "your-api-key-here",
           "GRAPHXR_URL": "https://graphxr.kineviz.com",
        }
      }
    }
  }
  ```

   Replace `/absolute/path/to/graphxr-mcp` with the real path to your clone (e.g. `/Users/you/kineviz/graphxr-mcp`).

3. **Restart Claude Desktop** so it picks up the new config and spawns the local MCP server.

4. **Optional:** Use `GRAPHXR_DEBUG`: `"true"` in `env` to see MCP debug logs (e.g. in the terminal if you launch Claude from the command line).

After changing the repo and running `yarn build` again, restart Claude (or reconnect the MCP) to load the updated build.

## Development

### Setup

```bash
# Install dependencies
yarn install

# Build for development (with sourcemaps)
yarn build:dev

# Build for npm package
yarn build
```

### Testing Locally with MCP Inspector

You can test the MCP server locally using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), a visual debugging tool for MCP servers:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

This will open a web interface where you can:
- View all available tools and their schemas
- Execute tools interactively and see responses
- Debug request/response payloads

Make sure to set the required environment variables before running:

```bash
# Set environment variables and run inspector
GRAPHXR_API_KEY=your-api-key GRAPHXR_URL=https://graphxr.kineviz.com npx @modelcontextprotocol/inspector node dist/index.js
```

Or export them first:

```bash
export GRAPHXR_API_KEY=your-api-key
export GRAPHXR_URL=https://graphxr.kineviz.com
npx @modelcontextprotocol/inspector node dist/index.js
```

The browser opens in headed mode by default (you'll see the browser window), which is recommended for better visibility and debugging. To run in headless mode instead, set:

```bash
export GRAPHXR_HEADLESS=true
```

### Project Structure

```
graphxr-mcp/
├── src/
│   ├── index.ts           # Main MCP server
│   ├── browser-session.ts # Playwright browser manager
│   └── graphxr-client.ts  # REST API client
├── scripts/
│   ├── build.ts           # Dev build script
│   └── build-package.js   # npm package build
├── dist/                  # Build output
├── package.json
├── tsconfig.json
└── README.md
```

## Publishing (for maintainers)

### Prerequisites

- npm account with access to the `@kineviz` scope
- Node.js 18 or later

### First-time Setup

1. **Create an npm account** (if you don't have one): https://www.npmjs.com/signup

2. **Request access** to the `@kineviz` scope from a team administrator

3. **Log in to npm** with the @kineviz scope:

```bash
npm login --scope=@kineviz
```

This will prompt you for your npm username, password, and email. If you have 2FA enabled, you'll also need to enter a one-time password.

4. **Verify you're logged in**:

```bash
npm whoami
```

This should display your npm username.

### Before Each Release

Verify your npm session is still active:

```bash
npm whoami
```

If you get an error, log in again:

```bash
npm login --scope=@kineviz
```

### Release Process

1. **Prefix commit messages with the Jira ticket ID** — All commits should be prefixed with the relevant Jira ticket (e.g. `GXR-3667 Add headless toggle to open_project`). This links commits to Jira for traceability.

2. **Create a new release:**

#### Using the Release Script (Recommended)

The easiest way to create a release is using the release script:

```bash
# Interactive mode (prompts for version type)
bash scripts/release.sh

# Or specify version type directly
bash scripts/release.sh patch   # 0.1.0 → 0.1.1 (bug fixes)
bash scripts/release.sh minor   # 0.1.0 → 0.2.0 (new features)
bash scripts/release.sh major   # 0.1.0 → 1.0.0 (breaking changes)
```

The release script will:
1. Check npm authentication (`npm whoami --scope=@kineviz`)
2. Show current version
3. Bump version in `package.json` (patch/minor/major)
4. Build the package (`yarn build`)
5. Publish to npm (`npm publish --access public`)

#### Using Cursor Slash Commands

If you're using Cursor IDE, you can use the slash commands:

- `/release` - Interactive release (prompts for version type)
- `/release:patch` - Create a patch release (bug fixes)
- `/release:minor` - Create a minor release (new features)
- `/release:major` - Create a major release (breaking changes)

#### Manual Release (Alternative)

If you prefer to do it manually:

```bash
# 1. Verify npm login
npm whoami --scope=@kineviz

# 2. Bump version
npm version patch  # or minor, or major

# 3. Build and publish
yarn release
```

The `yarn release` command will:
1. Build the package (`yarn build`)
2. Publish to npm with public access

#### After Release

After publishing, don't forget to:

1. Commit the version change:
   ```bash
   git add package.json
   git commit -m "Release vX.Y.Z"
   ```

2. Create a git tag:
   ```bash
   git tag vX.Y.Z
   ```

3. Push changes:
   ```bash
   git push origin main --tags
   ```

## License

MIT

## Support

For issues and feature requests, contact [Kineviz](https://kineviz.com).