Content
# SysML v2 MCP Server
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that exposes the **SysML v2 REST API** to AI assistants such as Claude, GPT, and any other MCP-compatible agent.
Supports **STDIO** (Claude Desktop / Claude Code) and **Streamable HTTP** (OpenAI Agents SDK / PLMgpt Gateway) transports.
> **Open source, MIT licensed. No commercial intent.**
---
## Compatible Backends
This server implements the [OMG Systems Modeling API and Services](https://www.omg.org/spec/SystemsModelingAPI/1.0/Beta1/About-SystemsModelingAPI) specification and works with any compliant SysML v2 server:
| Backend | Vendor | Notes |
|---|---|---|
| **Teamwork Cloud (TWC)** | Dassault Systèmes / 3DS | Full support including TWC-specific tools |
| **SysON** | Eclipse / Obeo | Standard OMG API tools; set `TWC_SYSMLV2_PATH=/api` |
| **SysML v2 Pilot Implementation** | OMG reference | Standard OMG API tools; usually no auth token needed |
| Any OMG-spec compliant server | — | Standard OMG API tools |
> Tools marked **[TWC]** in the tool table below are Teamwork Cloud specific and will not work on SysON or the pilot implementation.
---
## Quick Start
```bash
# 1. Clone and install
git clone https://github.com/your-org/sysmlv2-mcp-server.git
cd sysmlv2-mcp-server
npm install
# 2. Configure
cp .env.example .env
# Edit .env — at minimum set TWC_BASE_URL and TWC_TOKEN
# 3. Build
npm run build
# 4. Run (STDIO mode — default)
npm start
# Run in HTTP mode
MCP_TRANSPORT_MODE=http npm start
```
---
## Configuration
Copy `.env.example` to `.env` and set the values for your backend. All options are documented inline in `.env.example`.
| Variable | Default | Description |
|---|---|---|
| `TWC_BASE_URL` | *(required)* | Your SysML v2 server base URL |
| `TWC_SYSMLV2_PATH` | `/sysmlv2-api` | API path prefix (empty `""` for SysON/pilot, `/sysmlv2-api` for TWC) |
| `TWC_TOKEN` | *(required for TWC)* | API authentication token |
| `MAGICLAB_BASE_URL` | *(TWC only)* | MagicLab web UI URL for deep-link generation |
| `TWC_INSECURE` | `false` | Skip TLS verification (self-signed certs) |
| `MCP_TRANSPORT_MODE` | `stdio` | Transport: `stdio` or `http` |
| `MCP_HTTP_PORT` | `3001` | HTTP port (when mode=http) |
### Backend-specific setup
**Teamwork Cloud (TWC)**
```env
TWC_BASE_URL=https://your-twc-server:8443
TWC_SYSMLV2_PATH=/sysmlv2-api
TWC_TOKEN=your-api-token
MAGICLAB_BASE_URL=https://your-twc-server:8443/magiclab
TWC_INSECURE=true # if using self-signed cert
```
**SysON**
```env
TWC_BASE_URL=http://localhost:8080
TWC_SYSMLV2_PATH=
TWC_TOKEN= # leave blank if SysON has no auth
TWC_INSECURE=false
```
**SysML v2 Pilot Implementation (reference server)**
```env
TWC_BASE_URL=http://localhost:9000
TWC_SYSMLV2_PATH=
TWC_TOKEN= # no auth on reference server
TWC_INSECURE=false
```
---
## Claude Desktop Setup (Step-by-Step)
This server has been tested and validated on **Claude Desktop**.
### Step 1 — Clone and install
```bash
git clone https://github.com/your-org/sysmlv2-mcp-server.git
cd sysmlv2-mcp-server
npm install
```
### Step 2 — Configure your environment
```bash
cp .env.example .env
```
Open `.env` and set at minimum:
```env
TWC_BASE_URL=https://your-sysmlv2-server:8443
TWC_TOKEN=your-api-token
```
See the [Configuration](#configuration) section for all options and backend-specific examples.
### Step 3 — Build
```bash
npm run build
```
This compiles TypeScript to `dist/index.js`.
### Step 4 — Configure Claude Desktop
Open (or create) your Claude Desktop config file:
| Platform | Path |
|---|---|
| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` |
Add the following (adjust the path to where you cloned the repo):
**macOS / Linux**
```json
{
"mcpServers": {
"sysmlv2": {
"command": "node",
"args": ["/absolute/path/to/sysmlv2-mcp-server/dist/index.js"],
"env": {
"TWC_BASE_URL": "https://your-sysmlv2-server:8443",
"TWC_TOKEN": "your-api-token",
"TWC_SYSMLV2_PATH": "/sysmlv2-api",
"TWC_INSECURE": "true"
}
}
}
}
```
**Windows**
```json
{
"mcpServers": {
"sysmlv2": {
"command": "node",
"args": ["C:\\path\\to\\sysmlv2-mcp-server\\dist\\index.js"],
"env": {
"TWC_BASE_URL": "https://your-sysmlv2-server:8443",
"TWC_TOKEN": "your-api-token",
"TWC_SYSMLV2_PATH": "/sysmlv2-api",
"TWC_INSECURE": "true"
}
}
}
}
```
> **Tip:** You can pass all environment variables directly in the config `env` block instead of using a `.env` file — Claude Desktop will inject them when it starts the server.
### Step 5 — Restart Claude Desktop
Fully quit and relaunch Claude Desktop. You should see the SysML v2 tools available in the tools panel (hammer icon).
### Step 6 — Verify
Try asking Claude:
> *"List all my SysML v2 projects"*
If the server is connected, Claude will call `sysmlv2_get_projects` and return your project list.
For more example prompts see [EXAMPLES.md](./EXAMPLES.md).
---
## Transport Modes
### STDIO (default)
For Claude Desktop, Claude Code, or any MCP client that launches the server as a subprocess.
```json
{
"mcpServers": {
"sysmlv2": {
"command": "node",
"args": ["/path/to/sysmlv2-mcp-server/dist/index.js"],
"env": {
"TWC_BASE_URL": "https://your-sysmlv2-server:8443",
"TWC_TOKEN": "your-token"
}
}
}
}
```
### Streamable HTTP
For OpenAI Agents SDK, PLMgpt Gateway, or web-based MCP clients.
```bash
MCP_TRANSPORT_MODE=http MCP_HTTP_PORT=3001 npm start
```
Endpoints:
- `POST /mcp` — Streamable HTTP (primary)
- `GET /sse` — SSE (legacy)
- `GET /health` — Health check
---
## Tools (38 total)
### Project Services (5) — Standard OMG API
| Tool | Description |
|---|---|
| `sysmlv2_get_projects` | List all projects |
| `sysmlv2_get_project` | Get project by ID |
| `sysmlv2_create_project` | Create new project |
| `sysmlv2_update_project` | Update project name / description |
| `sysmlv2_delete_project` | Delete project (irreversible) |
### Commit Services (6) — Standard OMG API
| Tool | Description |
|---|---|
| `sysmlv2_get_commits` | List commits for a project |
| `sysmlv2_get_commit` | Get commit by ID |
| `sysmlv2_create_commit` | Create new commit with optional change set |
| `sysmlv2_diff_commits` | Diff two commits (ADDED / UPDATED / DELETED) |
| `sysmlv2_get_commit_changes` | Get change set for a commit |
| `sysmlv2_get_commit_change` | Get a specific change by ID |
### Branch Services (5) — Standard OMG API
| Tool | Description |
|---|---|
| `sysmlv2_get_branches` | List branches |
| `sysmlv2_get_branch` | Get branch by ID |
| `sysmlv2_create_branch` | Create new branch |
| `sysmlv2_delete_branch` | Delete branch (irreversible) |
| `sysmlv2_merge_branch` | Merge source commit into target branch |
### Tag Services (4) — Standard OMG API
| Tool | Description |
|---|---|
| `sysmlv2_get_tags` | List tags |
| `sysmlv2_get_tag` | Get tag by ID |
| `sysmlv2_create_tag` | Create tag on a commit |
| `sysmlv2_delete_tag` | Delete tag |
### Element Navigation (4) — Standard OMG API
| Tool | Description |
|---|---|
| `sysmlv2_get_elements` | Get all elements (paginated) |
| `sysmlv2_get_element` | Get element by ID |
| `sysmlv2_get_roots` | Get root elements — entry point for model traversal |
| `sysmlv2_get_element_relationships` | Get element relationships (IN / OUT / BOTH) |
### Query Services (7) — Standard OMG API
| Tool | Description |
|---|---|
| `sysmlv2_get_queries` | List saved queries |
| `sysmlv2_get_query` | Get query by ID |
| `sysmlv2_create_query` | Create saved query |
| `sysmlv2_update_query` | Update saved query |
| `sysmlv2_delete_query` | Delete saved query |
| `sysmlv2_execute_query` | Execute ad-hoc query |
| `sysmlv2_execute_query_by_id` | Execute saved query by ID |
### Evaluation Services (3) — **[TWC only]**
> These tools use Teamwork Cloud's parametric evaluation extension and are not part of the standard OMG API. They will not work on SysON or the pilot implementation.
| Tool | Description |
|---|---|
| `sysmlv2_evaluate` | Evaluate parametric model at project level |
| `sysmlv2_evaluate_commit` | Evaluate parametric model at a specific commit |
| `sysmlv2_export_evaluation_table` | Export evaluation results as a table (project level) |
| `sysmlv2_evaluate_commit_table` | Export evaluation results as a table at a specific commit |
### Convenience Tools (3)
| Tool | Backend | Description |
|---|---|---|
| `sysmlv2_get_requirements` | All | Query all RequirementUsage elements via server-side filter |
| `sysmlv2_get_views` | **[TWC]** | Query ViewUsage elements + MagicLab deep links |
| `sysmlv2_open_magiclab` | **[TWC]** | Generate MagicLab URL for a project or element |
---
## Authentication
The server tries authentication in this order and stops at the first success:
1. `Token {TWC_TOKEN}` header — TWC default
2. `Bearer {TWC_TOKEN}` header — OAuth / standard JWT
3. No auth — for open/unauthenticated servers (e.g. local pilot)
---
## Architecture
```
src/index.ts Single-file MCP server
├── Config Environment-based configuration
├── HTTP helpers apiRequest() with multi-auth fallback
├── Pagination Link-header based paginatedGet()
├── SysMLv2MCPServer Main class
│ ├── registerProjectTools()
│ ├── registerCommitTools()
│ ├── registerBranchTools()
│ ├── registerTagTools()
│ ├── registerElementTools()
│ ├── registerQueryTools()
│ ├── registerEvaluationTools() ← TWC specific
│ ├── registerConvenienceTools()
│ ├── runStdio()
│ └── runHTTP()
└── Auto-run STDIO when executed directly
```
To add new tools, create a `registerXxxTools()` method in the class and call it from `registerAllTools()`.
---
## Importing for HTTP Mode
```typescript
import { mcpServer, SysMLv2MCPServer } from "./dist/index.js";
// Run in HTTP mode
mcpServer.run("http");
```
---
## Contributing
Contributions welcome. To add support for a new tool or backend-specific extension:
1. Add a `registerXxxTools()` method in `SysMLv2MCPServer`
2. Call it from `registerAllTools()`
3. If the tool is backend-specific, add a `[TWC]` / `[SysON]` marker in the README tool table
4. Submit a PR with a brief description of what API endpoint you're wrapping
---
## License
MIT — free to use, modify, and distribute with attribution.
---
## Publishing to GitHub
### Prerequisites
- A [GitHub account](https://github.com)
- [Git](https://git-scm.com/downloads) installed on your machine
- [GitHub CLI](https://cli.github.com) (optional but makes it easier)
---
### Option A — Using GitHub CLI (recommended, easiest)
**Step 1 — Install GitHub CLI** (if not already installed)
```bash
# macOS
brew install gh
# Windows (via winget)
winget install GitHub.cli
```
**Step 2 — Log in**
```bash
gh auth login
```
Follow the prompts — choose GitHub.com → HTTPS → authenticate via browser.
**Step 3 — Navigate to the release folder**
```bash
# macOS / Linux
cd /path/to/mcp-sysmlv2-server-release
# Windows
cd C:\path\to\mcp-sysmlv2-server-release
```
**Step 4 — Initialise git and create the repo in one command**
```bash
git init
git add .
git commit -m "Initial release"
gh repo create sysmlv2-mcp-server \
--public \
--description "MCP server exposing the SysML v2 REST API to AI assistants (Claude, OpenAI Agents). MIT licensed." \
--push \
--source .
```
Done — your repo is live at `https://github.com/<your-username>/sysmlv2-mcp-server`.
---
### Option B — Using Git + GitHub website (manual)
**Step 1 — Create a new repo on GitHub**
1. Go to [https://github.com/new](https://github.com/new)
2. Set repository name: `sysmlv2-mcp-server`
3. Set description: `MCP server exposing the SysML v2 REST API to AI assistants. MIT licensed.`
4. Set visibility: **Public**
5. **Do NOT** check "Add a README", "Add .gitignore", or "Choose a license" — the repo must be empty
6. Click **Create repository**
7. Copy the repo URL shown (e.g. `https://github.com/<your-username>/sysmlv2-mcp-server.git`)
**Step 2 — Initialise git in the release folder**
```bash
cd /path/to/mcp-sysmlv2-server-release
git init
```
**Step 3 — Stage all files**
```bash
git add .
```
**Step 4 — Verify nothing sensitive is included**
```bash
git status
```
You should see only: `src/index.ts`, `package.json`, `tsconfig.json`, `.env.example`, `README.md`, `EXAMPLES.md`, `.gitignore`.
No `.env`, no `node_modules/`, no `dist/`.
**Step 5 — Create the first commit**
```bash
git commit -m "Initial release — SysML v2 MCP Server v1.0.0"
```
**Step 6 — Add the remote and push**
```bash
git remote add origin https://github.com/<your-username>/sysmlv2-mcp-server.git
git branch -M main
git push -u origin main
```
**Step 7 — Add a license on GitHub**
1. Go to your new repo on GitHub
2. Click **Add file → Create new file**
3. Name it `LICENSE`
4. Click **Choose a license template** → select **MIT**
5. Fill in your name → **Review and submit**
---
### After publishing — recommended GitHub settings
**Add topics** (improves discoverability):
Go to your repo → click the ⚙️ gear icon next to "About" → add topics:
`sysml` `sysmlv2` `mcp` `mbse` `model-context-protocol` `teamwork-cloud` `claude` `ai` `systems-engineering`
**Update the README repo URL:**
In `README.md`, replace:
```
git clone https://github.com/your-org/sysmlv2-mcp-server.git
```
with your actual URL:
```
git clone https://github.com/<your-username>/sysmlv2-mcp-server.git
```
Then commit and push:
```bash
git add README.md
git commit -m "Fix clone URL to actual repo"
git push
```
**Add a release tag:**
```bash
git tag -a v1.0.0 -m "v1.0.0 — Initial public release"
git push origin v1.0.0
```
Then on GitHub go to **Releases → Draft a new release** → select `v1.0.0` → write release notes → publish.
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available