Graphistry MCP server

Graphistry MCP Server provides GPU-accelerated graph visualization and analytics capabilities for Large Language Models. It integrates Graphistry's powerful visualization platform with the Model Control Protocol (MCP), enabling AI assistants to visualize complex network data and perform advanced graph analytics through a standardized interface.

Prerequisites

Before installing, you need a free Graphistry account:

1. Sign up at hub.graphistry.com
2. Keep your username and password ready for configuration

Installation

Setting Up with Python Virtual Environment

# Clone the repository
git clone https://github.com/graphistry/graphistry-mcp.git
cd graphistry-mcp

# Set up virtual environment and install dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Alternatively, use the provided setup script:

./setup-graphistry-mcp.sh

Configuring Credentials

Set your Graphistry credentials using one of these methods:

1. Environment variables:

   export GRAPHISTRY_USERNAME=your_username
   export GRAPHISTRY_PASSWORD=your_password
   

2. Create a .env file in the project root:

   GRAPHISTRY_USERNAME=your_username
   GRAPHISTRY_PASSWORD=your_password
   

MCP Configuration

Setting Up .mcp.json

Create your MCP configuration file by copying the example:

cp .mcp.json.example .mcp.json

Edit .mcp.json to configure:

• Correct paths for your environment
• Graphistry credentials (if not using environment variables)
• Connection mode (HTTP or stdio)

Running the Server

Starting in stdio Mode

# Activate your virtual environment if not already active
source .venv/bin/activate

# Start the server
python run_graphistry_mcp.py

Starting in HTTP Mode

# Using the recommended start script (securely loads .env)
./start-graphistry-mcp.sh --http 8080

Integrating with LLM Tools

Adding to Cursor

Add this to your .cursor/mcp.json:

{
  "graphistry": {
    "command": "/path/to/your/.venv/bin/python",
    "args": ["/path/to/your/run_graphistry_mcp.py"],
    "env": {
      "GRAPHISTRY_USERNAME": "your_username",
      "GRAPHISTRY_PASSWORD": "your_password"
    },
    "type": "stdio"
  }
}

Using the Graphistry MCP Tools

Visualizing a Simple Graph

{
  "graph_data": {
    "graph_type": "graph",
    "edges": [
      {"source": "A", "target": "B"},
      {"source": "A", "target": "C"},
      {"source": "A", "target": "D"},
      {"source": "A", "target": "E"},
      {"source": "B", "target": "C"}
    ],
    "nodes": [
      {"id": "A"}, {"id": "B"}, {"id": "C"}, {"id": "D"}, {"id": "E"}
    ],
    "title": "Simple Graph Example",
    "description": "A graph with 5 nodes and 5 edges"
  }
}

Visualizing a Hypergraph

{
  "graph_data": {
    "graph_type": "hypergraph",
    "edges": [
      {"source": "A", "target": "B", "group": "G1", "weight": 0.7},
      {"source": "A", "target": "C", "group": "G1", "weight": 0.6},
      {"source": "B", "target": "C", "group": "G2", "weight": 0.8},
      {"source": "A", "target": "D", "group": "G2", "weight": 0.5}
    ],
    "columns": ["source", "target", "group"],
    "title": "Test Hypergraph",
    "description": "A simple test hypergraph."
  }
}

Available MCP Tools

Graph Visualization

• visualize_graph: Create GPU-accelerated visualizations of graphs or hypergraphs

Graph Information

• get_graph_ids: List all stored graph IDs in the current session
• get_graph_info: Get metadata (node/edge counts, title, description) for a stored graph

Layout Options

• apply_layout: Apply standard layouts (force_directed, radial, circle, grid)
• apply_ring_categorical_layout: Arrange nodes in rings by categorical values
• apply_group_in_a_box_layout: Arrange nodes in group-in-a-box layout
• apply_modularity_weighted_layout: Arrange nodes by modularity-weighted layout
• apply_ring_continuous_layout: Arrange nodes in rings by continuous values
• apply_time_ring_layout: Arrange nodes in rings by datetime values
• apply_tree_layout: Arrange nodes in a tree (hierarchical) layout

Analysis Tools

• detect_patterns: Run network analysis (centrality, communities, paths, anomalies)

Visual Encoding

• encode_point_color: Set node color encoding
• encode_point_size: Set node size encoding
• encode_point_icon: Set node icon encoding
• encode_point_badge: Set node badge encoding
• set_graph_settings: Adjust advanced visualization settings

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "graphistry" '{"command":"/path/to/your/.venv/bin/python","args":["/path/to/your/run_graphistry_mcp.py"],"env":{"GRAPHISTRY_USERNAME":"your_username","GRAPHISTRY_PASSWORD":"your_password"},"type":"stdio"}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "graphistry": {
            "command": "/path/to/your/.venv/bin/python",
            "args": [
                "/path/to/your/run_graphistry_mcp.py"
            ],
            "env": {
                "GRAPHISTRY_USERNAME": "your_username",
                "GRAPHISTRY_PASSWORD": "your_password"
            },
            "type": "stdio"
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "graphistry": {
            "command": "/path/to/your/.venv/bin/python",
            "args": [
                "/path/to/your/run_graphistry_mcp.py"
            ],
            "env": {
                "GRAPHISTRY_USERNAME": "your_username",
                "GRAPHISTRY_PASSWORD": "your_password"
            },
            "type": "stdio"
        }
    }
}

3. Restart Claude Desktop for the changes to take effect