Enterprise Architect MCP Server
Read-only MCP server that gives AI agents access to Sparx Enterprise Architect .qea models without a running EA instance.
Full-text search across elements, attributes, operations, constraints, and notes, with case- and diacritic-insensitive matching
Retrieve full element details: notes, attributes, operations, diagrams, constraints, and multiplicity requiredness hints
List elements within a package, optionally filtered by type
Get incoming/outgoing/both connectors with feature-link resolution
Get elements and connectors on a diagram, including implied connectors
Read use case scenario flows with steps and attributes
Navigate the package hierarchy recursively
List and filter diagrams by name, type, or package
Resolve braced GUIDs or plain names to elements, diagrams, or packages with match confidence
Inspect the underlying database schema for additional data
Report model identity, file info, and configuration source
Windowed results with completeness metadata and continuation calls for paging
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Enterprise Architect MCP Server Show me the package structure under the root"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Enterprise Architect MCP Server
A read-only Model Context Protocol (MCP) server for Sparx Enterprise Architect .qea exports. Gives AI agents access to EA analysis models — search elements, navigate packages, read use case scenarios, and traverse connectors — without a running EA instance.
Works with any MCP client (VS Code / GitHub Copilot, Claude Desktop, Cursor, Windsurf). Reads the .qea SQLite export directly, never writes to it, and every response carries completeness metadata so an agent can tell a truncated answer from a complete one.
Keywords: MCP server · Sparx Enterprise Architect · .qea · UML · use case scenarios · package tree · connectors · diagrams · model search · AI agent tooling
Prerequisites
Node.js 22+ (uses the built-in
node:sqlitemodule)A
.qeafile exported from Sparx Enterprise Architect
Related MCP server: jgs-sysmlv2-api-mcp
Installation
VS Code / GitHub Copilot
The quickest route is the Install in VS Code badge at the top of this page. There is nothing to
fill in: the server asks for your .qea path the first time an agent queries the model, and
remembers the answer for next time.
To register it from a terminal instead, which is handier for scripting or a shared setup, use one CLI call:
code --add-mcp '{\"name\":\"enterprise-architect\",\"command\":\"npx\",\"args\":[\"-y\",\"enterprise-architect-mcp\"]}'The \" sequences are for the code shim, which re-parses the argument after PowerShell has
already handed it over — escaping with PowerShell's own backtick, or using --%, still arrives with
the quotes stripped. The single quotes stop PowerShell from touching the string. On bash or zsh the
plain form works instead:
code --add-mcp '{"name":"enterprise-architect","command":"npx","args":["-y","enterprise-architect-mcp"]}'To configure it by hand instead, add to your project's .vscode/mcp.json:
{
"servers": {
"enterprise-architect": {
"type": "stdio",
"command": "npx",
"args": ["-y", "enterprise-architect-mcp"]
}
}
}Nothing personal is in that file, so it can be committed as-is and each developer answers the prompt
once on their own machine. If you would rather not be asked at all, name the path up front — as a
trailing argument, in an env block, or in a gitignored .env in your workspace root:
EA_QEA_PATH=C:\EA\exports\model.qeaClaude Desktop
The same path-less configuration goes in claude_desktop_config.json (%APPDATA%\Claude\ on
Windows, ~/Library/Application Support/Claude/ on macOS):
{
"mcpServers": {
"enterprise-architect": {
"command": "npx",
"args": ["-y", "enterprise-architect-mcp"]
}
}
}Claude Desktop does not run the server from a workspace folder, so a .env there is not reliable.
If the client cannot show the path prompt at all, the server says so instead of failing silently, and
you can name the path in an env block:
"env": { "EA_QEA_PATH": "C:\\EA\\exports\\model.qea" }To run straight from source instead of npm, use "args": ["-y", "github:mm6502/enterprise-architect-mcp"].
Example Prompts
Once connected, try prompts like:
"Search for elements related to 'legal entity'"
"Show me the package structure under the root"
"What are the use case scenarios for UC_SUBMIT_APPLICATION?"
"What elements and connectors are on diagram 0103 Application Processing?"
"Resolve the reference {3F2A7C10-5B4D-4e8a-9C1F-27D6E8B0A4F3}"
"What columns does t_connector have?"
"Which diagrams does element a7680 appear on?"
Configuration
The server does not need a path to start. It looks for one when an agent first queries the model, and takes the first source that actually opens:
CLI argument —
mcp-server-ea C:\path\to\model.qeaEnvironment variable —
EA_QEA_PATH(set in anenvblock or system env).envfile —EA_QEA_PATH=...in a.envfile in the working directoryA remembered answer — whatever you last told the prompt
The prompt — the client asks, and a working answer is remembered for next time
If you would rather never see the prompt — a CI job, a shared image, or simply a preference — put
the path in a gitignored .env in the working directory. Copy the template:
Copy-Item .env.example .envThen set your local path in .env:
EA_QEA_PATH=C:\EA\exports\model.qeaIf the path points to a directory instead of a file, the server automatically picks the newest
.qea file in it by modification time — point it at your export folder and new exports are picked up
without reconfiguring anything:
EA_QEA_PATH=C:\EA\exports\The .env file is gitignored — each developer sets their own path without affecting the shared
config. It is also never committed, which is why it is the one route every new user has to set up by
hand; answering the prompt once is what makes that unnecessary.
A source naming a path that cannot be opened is skipped rather than fatal, so the next source gets
its turn. The reason goes to the server log, and once some later source opens, ea_get_model_info
lists it under skipped. That is deliberate — a sample value left in an env block would otherwise
outrank every answer you could give, and answering the prompt would never help. The cost is that a
genuine typo is demoted quietly, so check ea_get_model_info if the server opens a different model
than you expected.
Skipping is only worth it when an answer can take the skipped source's place, so two cases stay fatal: a path you passed on the command line (that is this run's explicit instruction, not a stale default), and any broken source in a client that cannot show a prompt — falling through there would quietly open some other model instead of telling you.
Answers are remembered per machine, in %APPDATA%\enterprise-architect-mcp\ on Windows,
~/Library/Application Support/enterprise-architect-mcp/ on macOS, and $XDG_CONFIG_HOME (or
~/.config) elsewhere; set EA_MCP_CONFIG_DIR to keep that file somewhere else. A path that does
not open is never remembered, so asking again is enough to correct a mistyped answer.
Available Tools
Tool | Description |
| Full-text search across elements, attributes, operations, and constraints. Takes |
| Same matching as |
| Full element detail — attributes, operations, diagrams it appears on, constraints (pre/post/invariant/process). Flags whether attribute multiplicity is contrastive. |
| List elements in a package, optionally filtered by type. Windowed: reports the total and pages with |
| Relationships for an element — includes feature-link resolution (which attribute/operation each end attaches to). |
| Elements and connectors on a diagram, including implied connectors and feature links. |
| Use case scenario steps with all attributes (trigger, uses, result, link, state) and scenario notes. A step's |
| Navigate the package hierarchy with recursive depth. |
| Search diagrams by name, type and package. Windowed like the tools above. |
| Resolve analyst references (braced GUID or plain name) to model candidates with full package path. Falls back to name-prefix matching for analyst codes; every candidate carries a |
| Introspect the model's database schema — tables, columns, indexes, rowid alias. |
| Identity of the open export — file name, size, modification date, server version, and which configuration source the path came from. |
Response contract
Every tool returns structured JSON with:
_meta.sourceTables— which database tables were consultedtotalMatched/returned/truncated— completeness metadata on every collectioncontinuation— exact call to retrieve the full set when truncatedisError: true+{ error: "not_found" }for non-existent subjects (distinct from empty results)
Two fields exist to stop an inexact answer from being read as a confirmed one:
ea_resolve—matchis always present; onlyprefixis an inexact matchea_get_element—_meta.attributes.multiplicityIsUniform: truemeans the element's attributes show no multiplicity contrast, so1..1is not evidence of requiredness
How Results Are Ordered, Paged, and Narrowed
Name ordering
Matching is locale-independent — search folds case and diacritics across European Latin alphabets,
so Straße, Łódź and Győr are found however they are typed or entity-encoded.
The enumeration tools — ea_search, ea_list_elements, ea_list_diagrams — do not order by name
at all. They order by the model's internal identity: stable and repeatable, but artificial, so
nothing should be read into which row follows which. That is a deliberate trade. Alphabetical
ordering under SQLite's binary collation sorts every accented initial after Z, and since these
tools return a window rather than the whole set, it does not merely reorder the list — it pushes
accented names out of the window entirely. Measured on a real export, names with an accented
initial filled 1.3% of visible slots under binary ordering against 3.0% under identity order, in a
model where they make up 3.9% of all names.
Only ea_get_scenarios still orders names by locale, where the whole set is always returned and no
name can be cut off. EA_LOCALE pins that ordering to a BCP 47 tag (sk, pl, hu, de, …) in
an env block or system env; unset, the host default applies. It does not affect matching.
Paging and narrowing
The enumeration tools return a window, not a sample. Each response carries totalMatched,
returned, offset and truncated, and when rows remain, a continuation naming the next call —
following it repeatedly visits every match once and terminates. Raising limit is not the way to
read a large set; advancing offset is.
When far more rows match than one window could hold, the response also carries a breakdown of how
they distribute. Its keys are parameter names and its values are argument values, so a breakdown is
a prompt to narrow — by objectType, stereotype, diagramType, or, for ea_search when the
result isn't already scoped, by packageScope (reported as the matching package's id, which the
next call can pass straight back) — rather than to page through thousands of rows.
License
Copyright (c) 2026 Michal Mracka
Licensed under the EUPL — see LICENSE for the full text.
Available Tools
12 toolsea_get_connectorsARead-only
Get all relationships (connectors) for a given element. connectors lists what the element is connected to and how (Realisation, Dependency, Association, etc.), each entry naming its source and dest ends. For Generalization connectors, source is always the specific (child) type and dest the general (parent) type — each end also carries a role making this explicit without needing to reason about direction. Filter by connectorType and direction to list an element's direct children (incoming Generalization) or direct parent(s) (outgoing Generalization) without a diagram. Feature links show which specific attribute or operation each end attaches to.
Inputs: elementId (required), direction, connectorType.
ea_get_diagram_elementsARead-only
Get all elements and connectors placed on a specific diagram: the diagram itself, plus elements and connectors. elements already includes free-text Note diagram objects, which often carry a legend or abbreviation definitions an agent would otherwise miss. Connectors include feature-link resolution showing which attribute or operation each end attaches to. The connector list is the union of explicit t_diagramlinks rows and implied connectors (both ends on the diagram).
Inputs: diagramId (required).
ea_get_elementARead-only
Get full details of an Enterprise Architect element by its ID, including its Note, attributes, operations, the diagrams it appears on, and its constraints. Attribute multiplicity supports a requiredness inference only when the element uses multiplicities contrastively; read _meta.attributes.multiplicityIsUniform before making that inference — when it is true the element's attributes carry no multiplicity contrast, so a value like 1..1 is not evidence of requiredness. Attributes and operations are capped inline: attributesTruncated/operationsTruncated say whether the returned list is partial, and attributesTotal/operationsTotal give the full counts, so never infer a count from the inline list alone.
Inputs: elementId (required).
ea_get_model_infoARead-only
Report which .qea export file the server has open: fileName is the citable identity, alongside fileSizeBytes, lastModified, and the serverVersion that produced the answer. The full local path is also returned as resolvedPath, with resolvedPathNote explaining why it is environment detail rather than something to cite. configuration says where that path came from — source in words, sourceId as one of argument/environment/dotenv/remembered/prompt, and the configured value behind it — plus any skipped settings, each with the reason it could not be opened, and shadowed ones a higher-priority source outranked; configurationNote says how much of that is safe to repeat.
Inputs: no named parameters.
ea_get_package_treeARead-only
Navigate the package hierarchy. Without parameters, returns top-level packages. With a packageId, returns that package's children up to the specified depth. Each node carries id, name, parentId, and elementCount.
Inputs: depth, packageId.
ea_get_scenariosARead-only
Get use case scenario flows for an element. scenarios holds the parsed flows; each has name, type, notes, and steps, and each step carries stepNumber plus its attributes (trigger, uses, result, state, link). Steps are numbered within each scenario. Scenarios ordered by type: Basic Path first, then Alternate, then Exception. A step's uses may name a business rule or constraint by code; that code is not independently searchable or resolvable — look it up among this same elementId's own constraints via ea_get_element, not by a separate lookup.
Inputs: elementId (required).
ea_get_schemaARead-only
List the model's database tables in tables, or pass a tableName to get that table's columns and indexes instead. That form echoes the table name and adds rowidAlias — the INTEGER PRIMARY KEY aliasing SQLite's rowid, so the fastest lookup path, or null when the table has none — with rowidNote saying which case applies. Use this to discover what data the model holds beyond what the typed ea_* tools return. See ea_get_model_info for the export's identity.
Inputs: tableName.
ea_list_diagramsARead-only
List diagrams in the model, optionally filtered by package, diagram type, and/or name substring. Each entry in results carries diagramId, name, type, packagePath, and eaGuid. Diagrams are ordered by the model's internal identity — stable but artificial, neither alphabetical nor the analyst's tree order — so adjacency carries no meaning. Walk a large result set with offset rather than a larger limit; while rows remain, continuation names the next call. When far more diagrams match than one window can hold, breakdown reports how many each type holds, so the next call can narrow by diagramType instead of paging.
Inputs: limit, offset, packageId, diagramType, +1 more.
ea_list_elementsARead-only
List elements within a package, optionally filtered by object type. elements is a lightweight list (ID, type, name, alias, stereotype), grouped by element type and then ordered by the model's internal identity. That order is stable but artificial — neither alphabetical nor the analyst's tree order — so adjacency carries no meaning. Walk a large package with offset rather than a larger limit; while rows remain, continuation names the next call. When far more elements match than one window can hold, breakdown reports how many each type holds, so the next call can narrow by objectType instead of paging.
Inputs: packageId (required), limit, offset, objectType.
ea_resolveARead-only
Resolve an analyst reference (braced GUID or plain name) to model candidates: the input is echoed as reference and the hits are in candidates. A braced GUID is matched exactly. A plain name is matched against the full name first; only if nothing matches exactly is the reference retried as a name prefix, which resolves analyst codes like UC_ABC_2079 or OA_ABC_2280 to elements named 'CODE: description'. An exact hit is returned alone and is never diluted by prefix hits. Each candidate reports its type (element, diagram, package), id, name, fullPackagePath, eaGuid, and a match field that is always present with value "guid", "exact", or "prefix" — a "prefix" candidate is an inexact match and must not be treated as a confirmed identity. Use the optional kind filter to narrow results.
Inputs: reference (required), kind.
ea_searchARead-only
Search Enterprise Architect model elements by name, alias, notes, attribute names/notes, operation names/notes, or constraint notes. Matching is case- and diacritic-insensitive across European Latin alphabets and sees through entity-encoded text. requiredTerms is a list of terms every one of which must occur somewhere in an element's searchable text (conjunction) — terms need not share a field, but sharing one ranks higher; each term is matched as a contiguous substring exactly as a single term is, so a term carrying whitespace is a phrase and is never split. A one-entry list behaves exactly as a single search term always has. boostAnyOf is an optional list of further terms: a result also matching at least one of them ranks ahead of one that does not, but nothing is ever excluded on that basis — for narrowing to only elements matching an alternative too, use ea_search_and_any_of instead. When no element matches, termMatches reports, per supplied term, whether that term matched anywhere in the corpus at all — so a caller can tell which term emptied the result rather than re-guessing the whole call. Matching elements are returned in results, strongest match first, each with a decoded note preview and a truncation flag; equally strong matches fall back to the model's internal identity, a stable but artificial order. Each result also carries matches, the evidence for why it was returned: the field that matched, the id and name of the attribute, operation or constraint it came from, and a snippet of the author's own text around the match. Evidence is strongest-first and capped, and _meta.matches on the result reports how many matches were found and how many were withheld. The note preview centres on the match when the element's own note is what matched. packageScope restricts results to a package (given as its id or its name) and its descendants. Walk a large result set with offset rather than a larger limit; while rows remain, continuation names the next call. When far more elements match than one window can hold, breakdown reports how they distribute — by objectType, stereotype, or, unless already scoped, by packageScope (reported as the matching package's id, which the next call can pass straight back) — so the next call can narrow instead of paging.
Inputs: requiredTerms (required), limit, offset, boostAnyOf, +3 more.
ea_search_and_any_ofARead-only
Search Enterprise Architect model elements the same way ea_search does, plus andAnyOf: a required-and-alternative filter. requiredTerms still works exactly as it does on ea_search (conjunction, contiguous substring, terms need not share a field). andAnyOf is an optional list of further terms; when supplied, a result must contain requiredTerms AND at least one andAnyOf term, so it can only ever narrow — it never returns a result requiredTerms alone would not. An empty andAnyOf array applies no filter. For promoting rather than narrowing, use ea_search instead, which offers the same alternatives idea as a rank boost. When no element matches the required terms at all, termMatches reports, per supplied term, whether it matched anywhere in the corpus. Matching elements are returned in results, strongest first, each with a decoded note preview, a truncation flag, and matches — the evidence for why it was returned, capped and strongest-first, with _meta.matches reporting how many were found and withheld. packageScope restricts results to a package and its descendants. Walk a large result set with offset; while rows remain, continuation names the next call. When far more elements match than one window can hold, breakdown reports how they distribute by objectType, stereotype, or packageScope.
Inputs: requiredTerms (required), limit, offset, andAnyOf, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Most tools target clearly distinct resources (packages, elements, connectors, diagrams, scenarios, schema), but `ea_search` and `ea_search_and_any_of` are effectively the same operation with one extra filter, and their descriptions spend most of their length explaining how they differ from each other. That is a parameter variation surfaced as a separate tool, which invites misselection. `ea_get_element` vs `ea_list_elements` is distinguishable, but the search pair drags the set down.
All names share the `ea_` prefix and follow a verb_noun pattern (`ea_get_element`, `ea_list_diagrams`, `ea_get_connectors`), which is highly predictable. Minor deviations: `ea_resolve` has no object noun, and `ea_search_and_any_of` encodes a parameter in the tool name rather than following the resource+action convention.
Twelve tools is a well-scoped surface for a read-only model browser, and each maps to a real artifact type in the .qea model. The count would be a clean 5 if the two near-duplicate search tools were merged into one with an optional filter.
The surface covers the main exploration paths: package hierarchy, element search and detail, element listing, connectors, diagram listing and contents, scenario flows, raw schema access, reference resolution, and export identity. Gaps remain around tagged values, standalone constraint/attribute/operation lookups, and any write capability, though a read-only inspector scope makes the latter a defensible design choice.
Maintenance
Related MCP Connectors
Read-only MCP server exposing a user ORANO library to their own AI agent.
Free, source-checked directory of AI agent tools, MCP servers and skills, with read-only search.
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Related MCP Servers
- AlicenseBqualityDmaintenanceA read-only MCP server connecting AI assistants to Azure DevOps Server (on-premises) for browsing projects, repos, builds, work items, releases, pipelines, and test results.39958 npm1MIT
- FlicenseNot gradedqualityBmaintenanceAn MCP server that gives an AI agent read and write access to a live SysML v2 model through the vendor-neutral OMG SysML v2 REST API.3-
- FlicenseAqualityCmaintenanceA read-only MCP server that enables AI clients to search a knowledge base and retrieve complete source documents via narrow search and fetch tools.2-
- FlicenseAqualityBmaintenanceA read-only MCP server that gives AI coding agents structured access to a project's source code, architecture, documentation, and Git context through 16 tools for searching, reading, and comparing evidence without modifying files.16-