MCP-ADAPTER

A single Model Context Protocol server that gives AI agents two things for fourteen engineering and design applications:

1. A comprehensive tool catalog – what each application can do, how every tool/command/function is used, with syntax, parameters, a runnable example and a documentation link. Fully searchable through MCP tools.

2. Headless automation adapters – run the real application when it is installed (batch/script mode), capture its output and return structured JSON.

Plus a timezone-aware time tool and an optional live documentation search (Tavily).

Catalog size

Catalogs live in mcp_adapter/catalogs/<software>/ as plain JSON, one category per file, following CATALOG_SCHEMA.md. They were compiled from the vendors' official documentation (MathWorks, Wolfram, COMSOL, Adobe, Cadence, Altium, Labcenter, AMD, Autodesk, Ansys, Altair, JGraph) and every entry records name, kind, description, usage, parameters, example, notes and docs.

Related MCP server: AutoCAD MCP Pro

Installation

git clone https://github.com/Babak-Solhjoo/MCP-ADAPTER-PV.git
cd MCP-ADAPTER-PV
python -m pip install -e ".[dev]"
mcp-adapter-setup        # answer two questions: local-only or network? internet tools on or off?

mcp-adapter-setup writes the answers to .env (creating it from .env.example if needed) and prints what they mean for the firewall. Skipping it is safe: the defaults are local-only and internet tools off.

Requirements: Python 3.10+, the mcp SDK (1.x and 2.x are both supported). Nothing else is needed for the catalog and time tools. For automation, the corresponding application must be installed on the same machine.

Quick start

1. Install as above. mcp-adapter-setup is optional; the defaults are local-only and offline.

2. Start the workspace UI and keep its console window open while you use it:

   python -m mcp_adapter.ui.server        # Windows without `python` on PATH: py -m mcp_adapter.ui.server

   Your browser opens the page by itself through a private link of the form http://127.0.0.1:8765/#t=<session key>; the same link is printed in the console window. The Applications tab lists all fourteen applications and marks the ones found on this computer.

3. Use it: chat with an agent in the Chat tab (store an Anthropic or OpenAI key in Settings first), or register the MCP server in Claude Desktop or Claude Code, which then start it themselves.

"This page needs its session key" or an empty application list? The page was opened without its private link: the address was typed or bookmarked, or the tab is older than the last UI start (the key changes on every start). Copy the http://127.0.0.1:8765/#t=... link from the UI's console window and open it or paste it into the box, or close the tab and start the UI again. Closing the console window (or Ctrl+C) stops the UI.

Use it only locally (licensing)

Recommendation: run MCP Adapter only locally, on the computer that holds your software licenses, and do not expose it on a public network or the internet. This is about software licenses, not about security: a connection can be perfectly secure and still break a license agreement.

Why it matters:

• MCP Adapter runs the applications installed on your computer (MATLAB and Simulink, Mathematica, COMSOL, Photoshop, OrCAD/PSpice, Altium, Proteus, Vivado, AutoCAD, HFSS, Feko, EAGLE) with your licenses.

• If the adapter is reachable over a public network or the internet (network mode, port forwarding, a tunnel, a cloud or shared server), anyone who can reach it can use those applications through your installation.

• Commercial licenses usually allow use only by the licensed person, on a specific computer or within a number of seats. They typically forbid remote use by others, sharing, and offering the software as a service (hosting, time-sharing, service bureau). Academic, student, trial and home licenses are often stricter still.

• Making the software available this way can therefore mean license violations, vendor audits, extra fees or a revoked license, for you or your organisation.

What to do:

• Keep the default local mode: the server and the workspace UI then answer only on this computer (127.0.0.1), never on the network or the internet.

• Use it yourself, as the licensed user. Do not share the endpoint, its token or the UI link with others.

• Do not publish it with port forwarding, tunnels or cloud hosting.

• If you really need remote or shared use, check each vendor's license agreement or ask your license administrator first.

This section is general information, not legal advice.

Security and network policy

The firewall is the last line of defence, not the only one. Two switches in .env decide what the server may do on the network, and the server enforces them itself at start-up and on every request:

What each transport does:

• stdio (default) – the MCP client starts mcp-adapter as a child process and talks over pipes. No socket is opened, no firewall prompt can appear for it.

• streamable-http / sse – a TCP listener. In local mode it is bound to 127.0.0.1 only. Windows Firewall may still show its "allow access" dialog the first time Python listens; deny it for local use (loopback traffic is exempt from firewall rules, so the server keeps working).

Check and change the policy at any time:

mcp-adapter --print-policy       # effective policy as JSON
mcp-adapter-setup --show         # current .env answers
mcp-adapter-setup                # interactive: re-answer the questions
mcp-adapter-setup --non-interactive --mode local --allow-internet no

Or edit the keys in .env directly and restart the server. Agents can call the security_policy tool to see which mode is active and why some tools are missing.

Note that the Claude desktop app and other MCP clients have their own local helper listeners and may trigger their own firewall prompts; those are unrelated to this server and can equally be denied for local use.

What an MCP client can do with this server

Treat every connected client (and the model behind it) as someone sitting at your keyboard:

• The automation tools run the installed applications with your user rights, and several of them execute code by design (matlab_run_code, mathematica_evaluate, comsol_run_python, vivado_run_tcl, autocad_run_lisp, hfss_run_script, altium_run_delphiscript, photoshop_run_jsx, ...). Connect only clients you trust, and switch off the applications you do not need (MCP_ADAPTER_ENABLE_<APP>=false or the Applications page).

• workspace_run (only registered when you switch on full folder access for a task) runs shell commands with the task folder as working directory; it is not a sandbox.

• The output-folder checks (set_output_folder) prevent mistakes such as writing into system folders or network shares; they do not confine the code-running tools above.

• API keys and the auth token live only in .env, which is git-ignored and readable only by your account; the UI accepts them write-only. The MCP server keeps them out of its environment, so the applications and shells it starts never see them; tool paths are not expanded (%VAR%), so a path cannot echo a key back; and the agent runner removes any key value from transcripts, chat history and reports.

• Tool paths may not point to network locations (UNC paths, mapped network drives): opening one would make Windows connect to another machine and possibly send your credentials.

• OPENAI_API_KEY is only sent to api.openai.com. A custom OpenAI-compatible endpoint (OPENAI_BASE_URL) gets OPENAI_COMPAT_API_KEY instead and must use HTTPS unless it runs on this computer.

• The agent is told to treat file contents, tool results and web pages as data, never as instructions, and a model can only call the tools it was given.

• Programs are never started from the current folder, and Program Files is searched before drive roots, so a planted matlab.bat cannot hijack a tool; on shared computers set the <APP>_EXE paths explicitly.

• The workspace UI binds 127.0.0.1 only and needs a per-session token on every API call, so other machines and other web pages cannot use it.

See SECURITY.md for how to report a vulnerability.

Where results are written

When you give a task a folder, the adapter writes its files into that folder, not into its own outputs folder.

• Claude Desktop and other long-running clients: the server starts once, before any task exists. The server instructions therefore tell the agent to call set_output_folder("D:\\Projects\\PCB") first whenever the user gives or grants a folder. From then on every generated script, netlist, log and result goes there, and relative paths in tool arguments are resolved inside it. Each application uses its own subfolder, for example D:\Projects\PCB\orcad, unless per_application_subfolders is false. An empty folder goes back to the default.

• Tasks started from the workspace UI or mcp-adapter-agent --work-dir: the server is started for that task with the folder as its output folder, so nothing needs to be called.

• No folder given: files go to MCP_ADAPTER_OUTPUT_DIR (default outputs/ in the repository).

The folder is checked in code before it is used:

• it must be an absolute path to an existing, writable folder on a local disk; the adapter never creates it;

• drive roots, the home folder itself, hidden folders, Windows/program/ProgramData/AppData folders and the adapter's own source folder are refused;

• network locations (UNC paths and mapped network drives) are refused, so results stay on this machine;

• MCP_ADAPTER_OUTPUT_ROOTS in .env (folders separated by ;) restricts the choice to those folders;

• a server started for one task working directory accepts only folders inside it.

These checks prevent mistakes; they are not a sandbox, because the scripting tools (MATLAB, Mathematica, COMSOL Java, Tcl, DelphiScript) run code with your user rights anyway. The setting belongs to the server process, so in Claude Desktop it applies to every chat until it is changed, reset or the app restarts. adapter_status and security_policy show the current folder and its source.

Workspace UI (chats, settings, applications, about)

python -m mcp_adapter.ui.server        # or: mcp-adapter-ui

This starts a tiny local web server and opens the page in your browser with a private link of the form http://127.0.0.1:8765/#t=<session key> (--no-browser only prints that link, --port 9000 changes the port). The key after #t= is new for every start and is needed to use the page, so another program or another user on the same computer cannot drive the UI; the part after # never leaves the browser. It runs until Ctrl+C; all settings live in .env and chats are stored as JSON under outputs/chats/, so nothing is lost when it stops. .env and the chat folder are made readable only by your account. Opening http://127.0.0.1:8765 without the key (typed address, bookmark, a tab from before a restart) shows a box asking for it: paste the link from the console window, or start the UI again (see Quick start).

The page has four tabs:

Chat - a Claude-desktop-like workspace, no other client needed:

• a sidebar with your chats; + New chat creates another one. Chats run in parallel, each with its own agent run and its own MCP server process, and each keeps its conversation history (later messages see the earlier turns).

• the conversation in the middle: your messages, the agent's answers (with "view steps" to open the run's report), and, while it works, every tool call and result live. Approve / Deny buttons appear when the chat has "Approve calls" switched on.

• the message box at the bottom with small option chips: Model (one dropdown with the models of every provider connected in Settings), Effort, the working folder (type a path or Browse... for the native folder dialog), Folder access, Approve calls, Reasoning and Max turns. Chip changes are saved to the chat immediately and become the defaults for new chats.

• Folder access gives the agent the workspace_* tools for that folder: list, read, write, move, delete and search, whose paths cannot leave the folder, plus workspace_run, which runs shell commands with the folder as working directory. workspace_run is a full shell, not a sandbox, so it always asks for approval, even when "Approve calls" is off. Keep folder access off for untrusted tasks. A drive root or your home folder is never given full access. All files the tools generate, and the run reports (agent-reports/), land in that folder.

Settings:

• Model providers - Anthropic and OpenAI keys (write-only), a light per provider: green = key stored and the provider answered, orange = key stored but not verified/unreachable, red = no key; Test re-checks and refreshes the live model list. Models of every provider with a key appear in the chat's model dropdown.

• MCP server for other LLM apps - use these applications from Claude Desktop, Claude Code, Cursor, VS Code and similar: ready-to-copy config for stdio clients (they start the server themselves) and a Start endpoint button that runs the server as a local HTTP MCP endpoint (http://127.0.0.1:8766/mcp, loopback only, optional autostart with the UI) for clients that connect to a URL. The endpoint requires the bearer token MCP_ADAPTER_AUTH_TOKEN, which the UI creates in .env on first start; clients send Authorization: Bearer <token> (the config snippets show where). An optional default working folder plus access switch applies to those external apps. ChatGPT's connectors need a server on the public internet, so a localhost endpoint is not visible to them without a tunnel, which is outside the local-only policy here.

• Security & network policy, adapter mode, timeout and output folder, as described above.

Applications - the grid with an on/off switch, real icon (read from the installed executable on Windows), detection status and executable path fields per application; Re-detect and Save live in the header.

About - what the application does, its version and license, the number of applications and catalog entries, and the author's GitHub, LinkedIn and e-mail.

The UI is hardened like the server: it binds 127.0.0.1 only; every API call carries the per-session key, which reaches the browser only through the launch link and is never embedded in the page; Host must be localhost and Origin must be the UI's own address; cross-origin preflights are refused; a strict content security policy with a per-response nonce blocks injected scripts; and secrets are never echoed back. Approvals are bound to the exact pending tool call. Restart the UI server after pulling Python changes; page changes show up on reload.

Adapter behaviour: only installed software is exposed

Most users have a few of the fourteen applications, not all of them. The server therefore works as an adapter:

• At start-up it looks for each application's executable (PATH, the usual vendor folders, or the <SOFTWARE>_EXE variable in .env).

• Automation tools are registered only for applications that were found. An agent that lists the tools sees matlab_* only if MATLAB exists on that machine; it never sees tools it cannot use and never has to discover a missing program by trial and error.

• Tools that need no executable are always present: drawio_create_diagram, drawio_flowchart, drawio_read, drawio_codec, orcad_parse_pspice_output, proteus_project_info, altium_script_template, feko_parse_out, feko_lua_template, eagle_read_design, eagle_bom, eagle_netlist.

• The catalog is always available for all fourteen applications, because knowing how a tool works is useful even when the software runs on another machine.

• list_software shows, per application, whether it is installed and which automation tools are available or hidden; adapter_status adds the reason for every hidden tool (which variable to set). The server instructions tell agents to consult these first.

• Installed something later? Set <SOFTWARE>_EXE if needed and restart the server; detection happens at start-up.

• MCP_ADAPTER_EXPOSE_UNAVAILABLE=true in .env registers every tool regardless (useful for demos and tests); calls for missing software then return ok: false with the same hint instead of failing.

Optional extras:

• pip install pywin32 – synchronous Photoshop/AutoCAD COM automation on Windows

• pip install mph – COMSOL Python scripting (comsol_run_python, comsol_model_summary)

• pip install pyaedt – HFSS through PyAEDT (hfss_run_pyaedt)

• pip install truststore – use the OS certificate store for Tavily calls behind corporate proxies

Which application for which task

Agents reach for the general tool (MATLAB) unless the server tells them what each application is built for. The MCP layer therefore carries this knowledge in five places:

• every automation tool description starts with a domain tag, e.g. [Ansys HFSS: 3D electromagnetic field simulation (antennas, RF/microwave, signal integrity)] ...;

• the server instructions contain the routing guide below, and the bundled agent's system prompt repeats it;

• list_software and software_overview return best_for, typical_tasks, not_ideal_for and prefer_over per application; software_overview also lists the application's capability areas (its catalog categories with entry counts), so an agent sees everything the program can do before choosing tools;

• recommend_application(task) ranks the applications for a task description, says which of them are installed on this machine and which tool prefix to use;

• compare_applications(task) compares the applications that can do the same kind of task, head to head (see Comparing applications for the same task).

Rule given to agents: prefer the specialised application whenever one fits and is installed; MATLAB is for numerics and post-processing around it. These are suggestions, not requirements: when the first choice is not installed, or the user asks for a different application, the agent uses an installed alternative and says what it gives up, instead of substituting silently. The profiles and keyword weights live in mcp_adapter/domains.py.

Comparing applications for the same task

Many tasks can be done by more than one application, and some do them better. mcp_adapter/comparisons.py holds a head-to-head comparison for 27 such task areas. Each area sums up in one line which application is best for which part of the job, and for every candidate it states its strength, when to choose it and its limits, ranked from the usual first choice.

The comparison is advisory:

• the suggested pick is the first installed candidate, so a missing application never blocks the work;

• when that is not the first choice, the advice names the first choice and the limits of the installed alternative, so the agent can tell the user what the substitution gives up;

• an installed application that the task names itself ("in Simulink", "with PSpice") wins over the ranking;

• candidates marked * below cover a neighbouring job only; they are listed for context and never offered as a substitute (Photoshop is not suggested for filter design, for example);

• if no suitable candidate is installed, the advice says so and names the first choice.

recommend_application(task) attaches the matching areas as comparison and lists installed alternatives. compare_applications() lists all areas, compare_applications(area="cfd") shows one area, and compare_applications(task="...") matches a description.

Example with OrCAD not installed but Simulink and MATLAB installed, for "simulate a buck converter":

First choice would be orcad (not installed). Suggested installed alternative: simulink. Control-loop design,
drive-level and grid-level behaviour, embedded code for the controller. Tell the user its limits: Device-level
waveforms are less detailed than PSpice with vendor models. Tools: simulink_*.

Configuration

Copy .env.example to .env. Everything is optional:

Call the adapter_status tool to see what was detected.

Running the server

There are two things you can run. Neither is running by itself after installation.

1. The MCP server is normally started by your MCP client (Claude Desktop, Claude Code, your own agent) as a child process that talks over stdio, so you usually never start it by hand: you register the command in the client (next section) and the client launches it when it connects. To run it manually, e.g. for an HTTP client:

python -m mcp_adapter.server                                            # stdio (default): opens no port
python -m mcp_adapter.server --transport streamable-http --port 8000    # listens on 127.0.0.1 only in local mode
python -m mcp_adapter.server --transport sse --port 8000
python -m mcp_adapter.server --transport streamable-http --host 0.0.0.0 # refused unless MCP_ADAPTER_NETWORK_MODE=network; mind the licensing note
python -m mcp_adapter.server --print-policy                             # show the effective security policy

The server prints its effective exposure to stderr at start-up, e.g. listening on 127.0.0.1:8000 - LOOPBACK ONLY. The HTTP transports refuse to start without MCP_ADAPTER_AUTH_TOKEN in .env (created by mcp-adapter-setup or the UI's Start endpoint); clients send it as Authorization: Bearer <token>. stdio needs no token.

2. The workspace UI (chats, settings, applications) is a small local web page; it runs while its console window is open and stops with Ctrl+C (see Workspace UI):

python -m mcp_adapter.ui.server

On Windows use py instead of python if the plain command is not on your PATH. The short commands mcp-adapter, mcp-adapter-setup and mcp-adapter-ui are installed too, but they only work when Python's Scripts folder is on your PATH; the python -m ... forms always work.

Claude Desktop

Add to claude_desktop_config.json (see examples/claude_desktop_config.json):

{
  "mcpServers": {
    "mcp-adapter": {
      "command": "python",
      "args": ["-m", "mcp_adapter.server"],
      "cwd": "C:/path/to/MCP-ADAPTER-PV"
    }
  }
}

Claude Code

claude mcp add mcp-adapter -- python -m mcp_adapter.server

(On Windows without python on PATH: claude mcp add mcp-adapter -- py -m mcp_adapter.server.)

Any MCP client (Python)

examples/client_demo.py launches the server over stdio, lists the tools and calls a few.

Tools

Catalog

Resources: catalog://software, catalog://{software}/categories, catalog://{software}/{name}.

Time

time_now, time_convert, time_add, time_difference, time_format, time_list_timezones, time_world_clock, time_unix. Inputs accept ISO 8601, unix seconds/milliseconds, now/today/tomorrow and common formats; zones accept IANA names, local, abbreviations (EST, CET, IST) and offsets (+03:30).

Automation (per application)

mathematica_wolfram_alpha is the only automation tool that reaches the internet (through your Mathematica installation); like search_docs_online it exists only when MCP_ADAPTER_ALLOW_INTERNET=true.

Every automation tool returns the same shape:

{"ok": true, "software": "matlab", "command": "...", "returncode": 0, "duration_s": 6.9,
 "stdout": "...", "stderr": "", "artifacts": {"script": "outputs/matlab/mcp_run_....m"}, "data": {"x": [1, 2, 3]}}

data carries structured results (JSON captured from MATLAB/Vivado/Photoshop/HFSS scripts, parsed PSpice output, diagram statistics, ...). When the executable is missing, ok is false and error names the environment variable to set.

Examples

search_tools(query="butterworth filter design", software="matlab")
describe_tool(software="mathematica", name="NDSolve")
matlab_eval(expression="roots([1 -3 2])")                  -> data.mcp_value__ == [2, 1]
simulink_simulate(model="vdp", stop_time="20")             -> logged signals summary + .mat file
vivado_build_project(project_file="C:/fpga/top.xpr")        -> WNS/TNS and bitstream path
drawio_flowchart(steps=["Load", "Valid?", "Save"], export_format="png")
hfss_export_touchstone(project="ant.aedt", design="patch", setup="Setup1", sweep="Sweep", output_file="ant.s1p")
time_convert(datetime="2026-09-19 14:30", from_timezone="Europe/Berlin", to_timezone="Asia/Tehran")

Notes on vendor entry points

• OrCAD Capture executes Tcl from its Command Window; a start-up switch differs between releases, so the adapter writes the script and returns the source command unless ORCAD_CAPTURE_TCL_CMD is configured.

• Altium Designer is driven with X2.EXE -RScriptFile:<PrjScr> -RProcName:<Unit>Proc>; override the switch template with ALTIUM_SCRIPT_ARGS if your version expects different names.

• Proteus has no documented headless simulation switch; proteus_run_cli passes arbitrary switches through.

• Feko (verified with 2026.1): runfeko MODEL [-np N] [--use-gpu] [--priority x] solves; cadfeko_batch MODEL.cfx -# VAR=VALUE --force-mesh changes variables and re-meshes; Lua scripts run with cadfeko / postfeko [MODEL] --non-interactive --run-script FILE [--configure-script "..."]. runfeko has no --version switch (the adapter parses its banner). The Lua templates follow the scripting reference; confirm method names with the CADFEKO recorder.

• EAGLE (verified with 9.6.0 in September 2026): Autodesk retired EAGLE on 7 June 2026 and shut down its licensing servers. The command-line CAM Processor still runs without signing in: eaglecon -X -N -dCAMJOB -j<job.cam> -o<dir> board.brd writes Gerber files, the Gerber job file, Excellon drill and assembly data (the adapter picks the shipped example_N_layer.cam job from the board's layer setup when none is given), and a legacy device plus a layer list (-dEXCELLON ... 44 45) writes a single file. The editor route (eagle -C "RUN x.ulp; QUIT") now stops at the Autodesk 'Sign in' window; the adapter detects that, closes the process and says so, and never signs in. .sch/.brd/.lbr files are XML (doc/eagle.dtd), so eagle_read_design, eagle_bom and eagle_netlist work without EAGLE; binary files from before EAGLE 6.0 are only read by the CAM Processor.

• COMSOL (verified with 6.4): comsolbatch -inputfile model.mph|Model.class -outputfile out.mph -batchlog log solves a model or runs a compiled Java model program; a model built by a class is saved as out_<ModelTag>.mph, which the adapter reports. comsolcompile exits with code 0 even when compilation fails, so the adapter checks its message and the .class file. comsol_inspect_model and comsol_evaluate compile small Java programs, so reading results needs no Python bridge (MPh stays optional). The example tools index the local Application Library (applications/) and its documentation (doc/help/.../com.comsol.help.models.*), including the Java script that builds each example; scripts/build_comsol_examples.py regenerates the example catalog from an installation.

• Photoshop must be running (or startable) on the same desktop session; COM (pywin32) gives synchronous execution, otherwise the adapter launches the JSX and polls for the result file.

Development

pytest -q                      # unit tests (live MATLAB test runs only when MATLAB is installed)
ruff check mcp_adapter tests scripts
python scripts/catalog_stats.py
python scripts/tavily_search.py "Vivado report_timing_summary options"

Project layout:

mcp_adapter/
  server.py          MCP tool/resource registration and CLI entry point
  catalog.py         catalog loader, alias resolution, ranked search
  time_tools.py      timezone-aware time utilities
  docs_search.py     Tavily-backed live documentation search
  config.py          .env loading, executable discovery, timeouts
  adapters/          one module per application (base.py holds the subprocess runner)
  catalogs/<id>/     meta.json + NN_<category>.json data files
tests/               pytest suite (catalog schema validation, time tools, adapters, server)
examples/            client demo and Claude Desktop configuration
scripts/             Tavily helper and catalog statistics

To add or extend a catalog, drop a new NN_<slug>.json file into the software folder (≤ 40 tools per file, fields per CATALOG_SCHEMA.md) and run pytest tests/test_catalog.py.

License

MIT, for the adapter's own code only. The applications it automates remain under their vendors' licenses; see Use it only locally (licensing).