MMAR-MCP Server

An MCP (Model Context Protocol) server that connects Large Language Models to the MM-AR metamodeling platform, enabling users to create complete metamodels and model instances through natural language interaction.

Overview

MMAR-MCP exposes the MM-AR platform's capabilities through the Model Context Protocol:

• 62 tools for authentication, metamodel CRUD, and instance CRUD operations

• 5 resources providing platform architecture docs, VizRep templates, the meta-model schema, attribute types, and a reference metamodel

• 3 prompts encoding guided workflows for metamodel creation, instance creation, and model analysis

The server communicates via STDIO transport and works with any MCP-compatible host (Cursor, Claude Desktop, or any client implementing the MCP specification).

Prerequisites

Quick Start

Follow these five steps to go from zero to a working setup.

Step 1: Start the MM-AR Platform

Option A: Full Docker deployment (recommended for first-time setup)

Clone and start the full MM-AR stack using Docker:

git clone https://github.com/MM-AR/mmar-docker-installation.git
cd mmar-docker-installation
docker compose --env-file .env up -d

Wait until all containers are healthy. You can check with:

docker compose ps

Option B: Hybrid deployment (PostgreSQL in Docker, services local)

This is the setup used during the thesis experiments. It requires cloning the main MM-AR repository:

# 1. Start PostgreSQL in Docker
docker run -d --name mmar_postgres \
  -e POSTGRES_USER=api -e POSTGRES_PASSWORD=root -e POSTGRES_DB=api \
  -p 5432:5432 postgres:16

# 2. Start the API server (requires mmar-server/.env with JWT_SECRET)
cd mmar-server
export $(cat .env | xargs)
cd ..
node dist/mmar-server/index.js

# 3. Start web clients (in separate terminals)
cd mmar-metamodeling-client && npm start   # port 8070
cd mmar-modeling-client && npm start        # port 8080

Once running, the following services are available:

Verify the API is up by visiting http://localhost:8000/login in your browser. You should see a login page. Default credentials: admin / admin.

Step 2: Clone and Build the MCP Server

git clone https://github.com/ProTech001/mmar-mcp-server.git
cd mmar-mcp-server
npm install
npm run build

The npm run build step compiles TypeScript to JavaScript in the dist/ folder. This step is required before the server can run.

Step 3: Verify the Installation

Run the end-to-end test suite to confirm everything works:

npm test

This spawns the MCP server as a child process and sends JSON-RPC messages via STDIO, exactly as a real MCP host would. It tests the handshake, authentication, tool listing, resource reading, prompt retrieval, and a full create/verify/delete cycle.

Expected output (all tests should pass):

==============================================
  MM-AR MCP Server — End-to-End Test
==============================================

  ✅ PASS  Initialize (handshake)
           → Server: mmar-mcp-server

  ✅ PASS  List Tools
           → 62 tools registered (expected 62)

  ✅ PASS  List Resources
           → 5 resource(s) (expected 5)

  ✅ PASS  Read Platform Info Resource
           → ...

  ...

==============================================
  Results: 16 passed, 0 failed, 16 total
==============================================

If any test fails, see the Troubleshooting section below.

Step 4: Configure Your MCP Host

The server runs over STDIO. Configure your MCP host to launch it as a subprocess.

Cursor IDE — create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "mmar": {
      "command": "node",
      "args": ["/absolute/path/to/mmar-mcp-server/dist/index.js"],
      "env": {
        "MMAR_API_URL": "http://localhost:8000"
      }
    }
  }
}

Claude Desktop — add to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "mmar": {
      "command": "node",
      "args": ["/absolute/path/to/mmar-mcp-server/dist/index.js"],
      "env": {
        "MMAR_API_URL": "http://localhost:8000"
      }
    }
  }
}

Replace /absolute/path/to/mmar-mcp-server with the actual path where you cloned the repository.

Step 5: Start Using

Once configured, the MCP host can invoke any of the 62 tools. Three guided prompts are available for common workflows:

1. create-metamodel — Create a new modeling language from a natural language description

2. create-model — Create a model instance using an existing metamodel

3. analyze-model — Inspect and analyze existing models

Example: "Use the create-metamodel prompt to create a Petri Net modeling language with Place nodes, Transition nodes, and Arc connections."

Configuration

The server reads one environment variable:

Set it via your shell, the MCP host config (see Step 4), or inline:

MMAR_API_URL=http://your-host:8000 node dist/index.js

Tool Catalog

All 62 tools are prefixed with mmar_ and grouped into three categories:

Authentication (3 tools)

Metamodel Operations (26 tools)

Instance Operations (33 tools)

All tool names carry the mmar_ prefix (e.g., mmar_create_class). The prefix is omitted in the table above for readability.

Resources

Project Structure

mmar-mcp-server/
├── src/
│   ├── index.ts              # Entry point (STDIO transport)
│   ├── server.ts             # MCP server setup and capability registration
│   ├── config.ts             # Configuration (reads MMAR_API_URL)
│   ├── api-client.ts         # MM-AR REST API client with JWT auth and retry logic
│   ├── tools/
│   │   ├── index.ts          # Tool registration hub
│   │   ├── auth.tools.ts     # Authentication tools (3)
│   │   ├── meta.tools.ts     # Metamodel CRUD tools (26)
│   │   └── instance.tools.ts # Instance CRUD tools (33)
│   ├── resources/
│   │   └── index.ts          # Resource definitions (5)
│   └── prompts/
│       └── index.ts          # Prompt definitions (3)
├── test-mcp.mjs              # End-to-end test suite
├── test-data/                 # Example payloads for MCP Inspector testing
│   ├── README.md
│   ├── example-ER-diagram-metamodel.json
│   └── example-petri-net-metamodel.json
├── package.json
├── tsconfig.json
└── .gitignore

Reproducible Evaluation Harness

Controlled trials (not Cursor chat). Start here:

→ experiments/README.md — setup, how to run, where JSON lives
→ experiments/EVALUATION-PROCEDURE.md — isolation / scoring protocol
→ experiments/harness-results/PRELIMINARY-RESULTS.md — Petri Net preliminary (6 trials)

cd experiment-harness
npm install
cp .env.example .env   # add ANTHROPIC_API_KEY; never commit .env

export MMAR_API_URL=http://127.0.0.1:8000
curl -s -o /dev/null -w "API %{http_code}\n" http://127.0.0.1:8000/login   # must be 200

npm run one -- --phase metamodel --language petri-net --trial a
npm run one -- --phase instance --language petri-net --trial a
npm run scoreboard
open ../experiments/harness-results/scoreboard.html

Prefer 127.0.0.1 over localhost if you see connection refused. Re-run npm run scoreboard after new trials.

npm run pilot                 # scorer self-test
npm run pilot -- --with-api   # + reset + MCP dry-run + GT seed (API must be up)

Testing with MCP Inspector

For interactive debugging, you can use the MCP Inspector:

npm run inspect

This opens a web UI where you can browse tools, call them manually, and inspect request/response payloads. See test-data/README.md for step-by-step instructions and example payloads.

Troubleshooting

ECONNREFUSED or "Cannot connect to MM-AR API"

The MM-AR platform is not running or not reachable at the configured URL.

1. Check that Docker containers are running: docker compose ps

2. Verify the API is up: curl http://localhost:8000/login

3. If using a custom URL, ensure MMAR_API_URL is set correctly

"Port 8000 already in use"

Another process is using port 8000. Either stop that process or configure the MM-AR platform to use a different port (see the mmar-docker-installation docs).

Tests fail at "Login as admin"

The MM-AR database may not be fully initialized yet. The Docker containers need a few seconds after startup to complete database initialization. Wait 10-15 seconds after docker compose up and retry.

"Cannot find module dist/index.js"

You need to compile the TypeScript source first:

npm run build

MCP host does not detect the server

• Ensure the path in your MCP host config points to the absolute path of dist/index.js

• Restart the MCP host after changing the configuration

• Check that Node.js v18+ is installed: node --version

Related Repositories

• mmar — Main MM-AR platform repository

• mmar-docker-installation — Docker-based setup for the full MM-AR platform

• mmar-server — MM-AR REST API server

License

ISC

Citation

If you use this software in your research, please cite:

@inproceedings{chima2026mmar-mcp,
  title={Agentic Creation of Modeling Languages: Extending the MM-AR Metamodeling Platform with MCP},
  author={Chima, Prosper and Fill, Hans-Georg and Curty, Simon},
  booktitle={Proceedings of the International Conference on Conceptual Modeling (ER), Demos and Posters},
  year={2026}
}