TigerGraph-MCP

Custom Discoveries TigerGraph-MCP V3.1 is a community based python Model Context Protocol server that exposes TigerGraph operations (queries, schema, vertices, edges, UDFs) as structured tools, prompts, and URI-based resources for MCP agents. This will allow you to interact with your TigerGraph Database using natural language commands!

Requirements
Features
Admin Features (New with V3.0)
Project Structure
Installation
Configuration
Running Chat Bot
Connecting to Claude Desktop
Contributing
License
Releases

Requirements

You will need to run TigerGraph Version >= 4.2.0, either in the cloud or in a Docker Image.
Make sure to add a TigerGraph dba user and set your password. Set role to: 'superuser' if you want to use the new Admin features
Setup local environment with Python >= 3.12 (run the installUVEnvironment.sh script)

Features

Schema Introspection
Retrieve full graph schema (vertex & edge types).
Query View
Retrieve list of available queires that your able to run
Query Execution
Run installed GSQL queries or raw GSQL strings with parameters.
Creation Vertex & Edge
Create Vertices and Edges programmatically
Alter Vertex
Allows for altering the Vertex to include support for Vector attributes
Upsert Vertex & Edge
Update vertices and edges attributes programmatically (this includes Vector attributes).
UDF & Algorithm Listing
Fetch installed user-defined functions and GDS algorithm catalogs.

Admin Features

To execute the Admin Features, your database user will need to have the database role of 'superuser'. None of the tools will show up in the /tools list if the user isn't assigned the 'superuser' role.

displayService_Status
This tool displays the database service status, show which services are on-line
displayDetailed_Service_Status
This tool provides all the detail that tool displayService_Status with additional information about the Graph to include vertices, edges, and installed queries
displayComponent_Version
This tool will display all the versions of the components that make up TigerGraph Server
displayCPUMemory_Usage
This tool will display both the CPU and Memory Usage of all the components that make up the TigerGraph Server
displayDiskSpace_Usage
This tool will display all the Disk Usage of the different components that make up the TigerGraph database server.

Features++ (Kick-Ass Features include)
1. We are including a mcp_chatbot that allow you "chat" with the database. You will need to configure
  two files. First, you will need to configure the mcp_server/.env file with the LLM you want to use
  (default is Anthropic LLM model) Second, you will need to configure the server_config.json file,
  under mcp_server/mcp_chatbot folder, specifying the full path to the main.py file.
  The chatbot usage is as follows:
  - @listQueries to see available Query Output Files
  - @ list content of Query file
  - /tools to list the available tools under the mcp server
  - /prompts to list the available prompts under the mcp server
  - /resources is a planned future enhancment
2. Custom Discoveries TigerGraph-MCP V3.1 now includes enhanced functionality for exporting
  query results to CSV or JSON file formats within a designated output directory. This output
  directory can be configured through the mcp_server/.env file, with the default location
  set to ./Output.
3. We have developed some Session Management Features that will help the developer with
  handling TigerGraph Session around SECRET & TOKEN Management. In short, TigerGraph session
  initialization checks the following:
4. Determines if the database is running (ping)
5. Determines if the specified graph in the .env file exists, if not, it will create a graph
6. Checks to see if there is a Secret registered by the combination of db user name and graph name
  (i.e. Secret Alias), if there is no Secret Alias, the system will create a secret and token and
  write it out to your .env file
7. Once the session is authenticated it will set a TigerGraph Connection

Project Structure

              TigerGraph-MCP/
├── installUVEnvironment.sh   # Intitalizes vitural environment if one exists, if not it will
                                create one, and load it with the project dependencies in the
                                requirements.txt file.
├── LICENSE                   # MIT License
├── main.py                   # MCP app bootstrap (`run_server()`) Used to start TigerGraph_MCP server
├── chatBot_Main.py           # Main python program to invoke mcp_chatbot.py
├── mcp_server
      ├── .env                # TigerGraph (HOST, GRAPH, SECRET) & LLM configuration paramaters
      ├── config.py           # Reads environment config file (.env) and defines System Constants
      ├── mcp_logger.py       # Sets up the log handler and sets Logging Level to ERROR
      ├── agents
            ├── ag2                # Directory that holds AG2 Agents
                 ├── chatAgent.py  # Chatbot using AG2 agent framework for LLM
            ├── agent_interface.py # Interface for implementing ChatAgent
            ├── prompts            # Directory that holds AG2 Agent prompts
                  ├── toolKitPrompt.py  # Prompts used by AG2 agent
            ├── toolBoxes          # Directory that holds AG2 Agent functions / "tools"
                  ├── mcpToolBox.py.    # Holds the functions / "tools
      ├── mcp_chatbot
            ├── mcp_chatbot.py     # Chatbot for LLM to interact with TigerGraph MCP Server (uses .env file)
            ├── server_config.json # Configuration file to define TigerGraph MCP Server
      ├── tigerGraph
            ├── interface.py      # Interface definitions of client methods
            ├── mcp_Server.py     # `@mcp.tool` and `@mcp.prompts` definitions, exposing client methods & prompts
            ├── prettyPrintDir.py # Implements pretty print directory functionality
            ├── services.py       # Implement service calls to TigerGraph database
            ├── session.py        # Encapsulates TigerGraphConnection and core session operations
       
├── Outputs                   # Output directory where Query outputs are written (.csv or .json format)
├── tests                     # test directory which containts all the tests cases written
    ├── README.md             # ReadMe file that has all the descriptions of the test cases in the tests directory
├── pyproject.toml            # Project metadata & dependencies
├── README.md                 # This markdown README file
├── requirements.txt          # Python package dependencies
├── runChatBot.sh             # Unix shell script to run TigerGraph ChatBot 
└── .gitignore                # Github/OS/Python ignore rules
            

Installation

Clone the repo

              git clone https://github.com/customdiscoveries/TigerGraph_MCP.git
cd TigerGraph-MCP
            

Copy Example Configuration files

              cp mcp_server/.env-example .env
cp mcp_server/mcp_chatbot/example-server_config.json server_config.json
            

Create, Install Dependencies & Activate a virtual environment
```
installUVEnvironment.sh
```

Configuration Setup

MCP TigerGraph Server

The assumption is that the developer has a instance of TigerGraph
running either in the cloud or on a Linux Desktop. Furthermore, it
is assumed that the TigerGraph instance has a defined dba user
(with valid roles and password).

Please edit your .env configuration (that you copied from the .env-exmaple) file
with the following required attributes to create a TigerGraph session:

TG_HOST=http://localhost
TG_GRAPH=tigerGraph_Graph_name
TG_USERNAME=tigerGraph_dba_user_name
TG_PASSWORD=tigerGraph_dba_user_password
TG_SECRET=(automatically captured if you don't provide one)
TG_TOKEN=(automatically captured if you don't provide one)

TigerGraph MCP ChatBot

The MCP ChatBot currently supports two LLMs, OPEN AI, an Anthropic claude.

You will need to modify the .env (same as used in the mcp server) configuration
file and set the LLM_MODEL_FAMILY attribute.

LLM_MODEL_FAMILY='ANTHROPIC' # Currently supports: 'ANTHROPIC' or 'OPENAI'
ANTHROPIC_LLM_MODEL='claude-3-7-sonnet-20250219'
ANTHROPIC_API_KEY="Your Anthropic Key goes here"
ANTHROPIC_TOKENS=2024
OPENAI_LLM_MODEL='gpt-4.1-mini'
OPENAI_TOKENS=2024
OPENAI_API_KEY="Your Open AI Key goes here"

You will need to update the server_config.json file (that you made a copy of) and
edit the path to the run command with your full path name:

"args": ["run", "/Your full path goes here/MCP-Repository/TigerGraph-MCP/main.py"]

Running Chat Bot

Once you have completed all of your configuration setup. It is now time to see the fruit of your labor!
To run the Chat Bot simply invoke the script runChatBot.sh

. runChatBot.sh

You should see a Welcome Banner:

              Welcome to Custom Discoveries TigerGraph MCP Chatbot!
Type your queries or type ['quit'|'exit'] to exit.
Use /tools to list available tools
Use /prompts to list available prompts

Query:
            

At the Query prompt type /tools to get a list of avaialbe tools to interactive with TigerGraph Graph database.

Connecting to Claude Desktop

This MCP server can be installed into the Claude Desktop client so that Claude can invoke your TigerGraph tools directly:
See link for setting up Claude Desktop at: https://modelcontextprotocol.io/quickstart/user#2-add-the-filesystem-mcp-server

Modify the configuration file at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
After configuring claude_desktop_config.json file, restart Claude Desktop and you’ll see your MCP tools available via the hammer 🛠 icon.

Contributing

Fork the repository
Create a feature branch
```
git checkout -b feature/YourFeature
```
Commit your changes
```
git commit -m "Add YourFeature"
```
Push to branch
```
git push origin feature/YourFeature
```
Open a Pull Request

Please ensure all new code is covered by tests and follows PEP-8 style.

License

This project is licensed under the MIT License.

Releases

V3.1 is the latest release that can be found at:[https://github.com/custom-discoveries/TigerGraph_MCP/releases/tag/V3.1]

TigerGraph MCP Server