@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 - 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

npx playwright install chromium

3. Configure Your MCP Client

Cursor IDE

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

{
  "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):

{
  "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 ≥ 2.0: raw markdown; older: JSON converted to markdown)
• grove_upload - Upload markdown as a grovebook (Grove ≥ 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 ≥ 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 < 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:

{
  "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):

   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:

   {
     "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, a visual debugging tool for MCP servers:

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:

# 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:

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:

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:

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:

npm whoami

This should display your npm username.

Before Each Release

Verify your npm session is still active:

npm whoami

If you get an error, log in again:

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:

# 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:

# 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:

   git add package.json
   git commit -m "Release vX.Y.Z"

2. Create a git tag:

   git tag vX.Y.Z

3. Push changes:

   git push origin main --tags

License

MIT

Support

For issues and feature requests, contact Kineviz.