siemens-graph-studio-mcp-server 0.4.4

MCP (Model Context Protocol) server for Siemens Graph Studio - enables AI agents to interact with knowledge graphs via SPARQL

Siemens Graph Studio MCP Server

An MCP (Model Context Protocol) server that enables AI agents to interact with Siemens Graph Studio knowledge graphs via SPARQL queries.

Features

• 🔍 Execute SPARQL Queries - Run queries against GraphMarts with automatic result formatting
• 📊 Smart Knowledge Discovery - Intelligent property categorization (object vs data properties) for better query generation
• 🔄 Manage GraphMarts - Create and modify transformation layers and steps
• 🧠 AI-Powered Queries - Natural language to SPARQL translation (with OpenAI)
• 📦 Ontology Caching - Efficient schema discovery with persistent caching
• 🏗️ Modular Architecture - Well-organized tool categories for maintainability

What's New in 0.4.x

• ✅ 0.4.4: explanation parameter is now optional in all graphmart layer/step tools — no longer a required field
• 🔌 0.4.3: Fixed REST API HTTP 400 errors by adding missing Accept: */* header
• 📦 0.4.2: Removed external anzo-api-wrapper dependency — replaced with a self-contained AnzoRestClient using Python stdlib only (no more requests==2.31.0 conflicts)
• 🔄 0.4.0: All 11 graphmart tools migrated from SPARQL journal writes to the REST API

See CHANGELOG.md for full details.

VS Code Setup (Recommended)

No API_KEY needed! GitHub Copilot handles natural language — the MCP server only needs credentials to connect to your Graph Studio instance.

Step 1 — Install the package

pipx install siemens-graph-studio-mcp-server
# Verify it works:
siemens-graph-studio-mcp --verify

Command not found? See Installation Guide.

Step 2 — Gather your Graph Studio credentials

You need four connection values from your Graph Studio administrator or the Graph Studio UI:

Variable	Where to find it	Example
ANZO_SERVER	Hostname of your Graph Studio server	graphstudio.mycompany.com
ANZO_PORT	HTTP/HTTPS port (check with your admin)	8443
ANZO_USERNAME	Your Graph Studio login username	jsmith
ANZO_PASSWORD	Your Graph Studio login password	••••••••
GRAPHMART_URI	URI of the target GraphMart (see below)	http://…/Graphmart/abc123

How to find your GRAPHMART_URI:

1. Open Graph Studio in a browser and log in
2. Navigate to the GraphMart you want to use
3. Click the GraphMart name to open its detail view
4. Copy the URI from the browser address bar — it looks like:

   http://graphstudio.mycompany.com:8443/graphmart/view?datasource=http%3A%2F%2F...%2FGraphmart%2Fabc123
   

5. Decode the datasource= parameter value — that decoded URL is your GRAPHMART_URI:

   http://cambridgesemantics.com/Graphmart/abc123
   

   Alternatively, in Graph Studio go to Settings → GraphMart Info — the URI is shown there directly.

Step 3 — Create .vscode/mcp.json

In your project root, create the file .vscode/mcp.json:

{
  "servers": {
    "graph-studio": {
      "type": "stdio",
      "command": "siemens-graph-studio-mcp",
      "env": {
        "ANZO_SERVER": "graphstudio.mycompany.com",
        "ANZO_PORT": "8443",
        "ANZO_USERNAME": "your-username",
        "ANZO_PASSWORD": "your-password",
        "GRAPHMART_URI": "http://cambridgesemantics.com/Graphmart/your-id"
      }
    }
  }
}

Tip: Auto-generate a template with the correct command path:

cd your-project
siemens-graph-studio-mcp --setup-vscode
# Then edit .vscode/mcp.json to fill in your real values

Command not in PATH? Use the full absolute path:

"command": "/Users/yourname/.local/bin/siemens-graph-studio-mcp"

Find it with: which siemens-graph-studio-mcp

Step 4 — Enable MCP in VS Code

1. Open Settings (Cmd+, / Ctrl+,)
2. Search for chat.mcp.enabled
3. Enable the checkbox ✓

Step 5 — Reload and verify

1. Cmd+Shift+P → "Developer: Reload Window"
2. Open Copilot Chat (Cmd+Shift+I)
3. Click the tools icon (wrench) — you should see Graph Studio tools listed
4. Try asking:
   • "What ontologies are available in the GraphMart?"
   • "Show me classes in the default ontology"
   • "Execute: SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 5"

Not working? See Installation Guide for troubleshooting.

Documentation

• Installation Guide - Detailed setup, troubleshooting, and PATH configuration
• Agent System Prompt - Recommended workflow and tool usage for AI agents
• SPARQL Reference - Query patterns, naming conventions, and troubleshooting
• Architecture Guide - Technical architecture overview
• Skills Documentation - Best practices for ontology and linking patterns

Installation

Recommended: pipx or uv (Isolated Environment)

# Using pipx (prevents dependency conflicts)
pipx install siemens-graph-studio-mcp-server

# Or using uv (faster)
uv tool install siemens-graph-studio-mcp-server

Alternative: pip

pip install siemens-graph-studio-mcp-server

Verify Installation

siemens-graph-studio-mcp --verify

Command not found? See Installation Guide for PATH troubleshooting.

Quick Start

1. Configure Environment Variables

export ANZO_SERVER="graph-studio.example.com"
export ANZO_PORT="8443"
export ANZO_USERNAME="your-username"
export ANZO_PASSWORD="your-password"
export GRAPHMART_URI="http://example.com/Graphmart/your-graphmart-id"

# Optional: Only for server-side natural language to SPARQL translation
# NOT needed when using VS Code Copilot (Copilot generates SPARQL for you)
# Basic SPARQL, discovery, and ontology tools work without this
export API_KEY="sk-your-openai-api-key"

2. Run the Server

siemens-graph-studio-mcp

3. Use with VS Code + GitHub Copilot (Recommended)

VS Code with GitHub Copilot provides a powerful way to use the MCP server without requiring an OpenAI API key. Copilot's built-in AI handles natural language understanding.

Step 1: Create a .vscode/mcp.json in your project:

{
  "servers": {
    "graph-studio": {
      "command": "siemens-graph-studio-mcp",
      "env": {
        "ANZO_SERVER": "graph-studio.example.com",
        "ANZO_PORT": "8443",
        "ANZO_USERNAME": "your-username",
        "ANZO_PASSWORD": "your-password",
        "GRAPHMART_URI": "http://example.com/Graphmart/your-graphmart-id"
      }
    }
  }
}

Note: No API_KEY required - GitHub Copilot handles the AI layer.

Step 2: Enable MCP in VS Code settings (Settings → Extensions → GitHub Copilot Chat → Enable MCP).

Step 3: Open Copilot Chat (Ctrl+Shift+I / Cmd+Shift+I) and ask questions like:

• "What classes are available in the GraphMart?"
• "Show me all properties of the Customer class"
• "Write a SPARQL query to find all active projects"

⚠️ Troubleshooting VS Code + Copilot

Command not found in VS Code:

// Use full path in .vscode/mcp.json if command not in PATH:
{
  "servers": {
    "graph-studio": {
      "command": "/full/path/to/siemens-graph-studio-mcp",
      // Find path with: siemens-graph-studio-mcp --verify
      ...
    }
  }
}

MCP tools not appearing:

1. Run "Developer: Reload Window" (Ctrl+Shift+P → Reload)
2. Check Output panel → "MCP" for errors
3. Verify the command works in terminal: siemens-graph-studio-mcp --verify

See full troubleshooting guide: docs/INSTALLATION_GUIDE.md

4. Use with Claude Desktop

Add to your ~/.config/claude-desktop/claude_desktop_config.json:

{
  "mcpServers": {
    "graph-studio": {
      "command": "siemens-graph-studio-mcp",
      "env": {
        "ANZO_SERVER": "graph-studio.example.com",
        "ANZO_PORT": "8443",
        "ANZO_USERNAME": "your-username",
        "ANZO_PASSWORD": "your-password",
        "GRAPHMART_URI": "http://example.com/Graphmart/your-graphmart-id",
        "API_KEY": "sk-your-openai-api-key"
      }
    }
  }
}

the server to do natural language to SPARQL translation internally. With Claude Desktop, this enables asking questions like "show me all customers" and having the server convert them to SPARQL automatically

Note: API_KEY is optional. Include it only if you want natural language to SPARQL translation. Basic SPARQL execution, knowledge discovery, and GraphMart management work without it.

Configuration

Environment Variables

Variable	Required	Description
ANZO_SERVER	Yes	Graph Studio server hostname
ANZO_PORT	Yes	Server port (typically 8443)
ANZO_USERNAME	Yes	Authentication username
ANZO_PASSWORD	Yes	Authentication password
GRAPHMART_URI	Yes	Target GraphMart URI
API_KEY	No	OpenAI API key - only needed for NL→SPARQL. All basic operations work without it.
ENABLE_AGENT_DEBUG	No	Enable debug output
ENABLE_LOGGING_DEBUG	No	Enable detailed logging

Config File

Alternatively, use a config file:

siemens-graph-studio-mcp --config my-config.json

See examples/config.example.jsonc for a template.

Architecture

The server is organized into focused, maintainable modules:

siemens_graph_studio_mcp/
├── server.py              # MCP server entry point
├── sparql_agent_core.py   # Core agent logic
├── ontology_discovery.py  # Schema extraction
├── ontology_cache.py      # Persistent caching
├── models.py              # Pydantic data models
├── tools/
│   ├── discovery/         # Knowledge exploration tools
│   ├── query/             # SPARQL execution tools
│   ├── ontology/          # Ontology management tools
│   ├── graphmart/         # GraphMart construction tools
│   └── system/            # System monitoring tools
└── utils/                 # Shared utilities

Key Components

• SPARQLAgent: The intelligent agent that converts natural language to SPARQL queries
• OntologyDiscovery: Extracts and analyzes ontology schemas from GraphMarts
• OntologyCache: Provides persistent caching for schema information
• Property Detection: Distinguishes between owl:ObjectProperty (relationships) and owl:DatatypeProperty (attributes) for smarter query generation

Available Tools

System & Monitoring

• test_system_connection - Test MCP server and Graph Studio agent status
• get_session_logs - Get session logs and interaction history

SPARQL Query Execution

• execute_sparql_query - Execute SPARQL directly against GraphMart
• query_ags_configuration - Query Graph Studio configuration
• update_ags_configuration - Update Graph Studio configuration

Knowledge Discovery

• discover_knowledge_overview - Get overview of available knowledge
• discover_available_ontologies - List all available ontologies
• discover_ontology_classes - List classes in a specific ontology
• discover_class_data_properties - List data properties for a class
• discover_class_object_properties - List object properties for a class

Ontology Management

• create_ontology - Create new ontologies
• delete_ontology - Delete ontologies
• load_ontology_from_file - Load TTL files into named graphs
• register_ontology - Register ontologies
• add_ontology_class / remove_ontology_class - Manage classes
• add_ontology_property / remove_ontology_property - Manage properties
• get_ontology_cache_status / clear_ontology_cache / refresh_ontology_cache - Cache management

GraphMart Construction

• create_transformation_layer - Create transformation layers
• add_transformation_step - Add transformation steps
• add_direct_load_step - Add direct data loading steps
• update_transformation_layer / delete_transformation_layer - Layer management
• list_transformation_layers / list_transformation_steps - List components
• refresh_graphmart / reload_graphmart - GraphMart operations

Transport Modes

stdio (default)

For use with Claude Desktop and other MCP clients:

siemens-graph-studio-mcp

SSE (Server-Sent Events)

For web clients:

siemens-graph-studio-mcp --transport sse --port 8000

HTTP Streaming

siemens-graph-studio-mcp --transport streamable-http --port 8000

Programmatic Usage

import asyncio
from siemens_graph_studio_mcp import GraphmartConfig, SPARQLAgent

async def main():
    config = GraphmartConfig(
        ags_server="graph-studio.example.com",
        ags_port=8443,
        graphmart_uri="http://example.com/Graphmart/demo",
        username="admin",
        password="secret"
    )
    
    agent = SPARQLAgent(config)
    await agent.initialize()
    
    # Now use the agent...

asyncio.run(main())

Development

Setup

git clone https://github.com/siemens/graph-studio-mcp-server.git
cd graph-studio-mcp-server
pip install -e ".[dev]"

Running Tests

pytest

Building for Distribution

pip install build twine
python -m build

Publishing to PyPI

# Test PyPI
twine upload --repository testpypi dist/*

# Production PyPI
twine upload dist/*

Requirements

• Python 3.10+
• Access to a Siemens Graph Studio instance
• Valid user credentials with GraphMart access

License

Apache License 2.0 - See LICENSE for details.

Related

• Model Context Protocol - The MCP specification
• Siemens Graph Studio - Knowledge graph platform
• FastMCP - Python MCP framework

Support

For issues and feature requests, please use the GitHub Issues page.