proteus-mcp
Enables working inside Proteus 8.6 projects: opening and modifying schematics, placing and wiring components, reading netlists and pin connectivity, attaching and building 8086 firmware with MASM, running and controlling simulations, reading simulation logs, taking screenshots, and inspecting instruments and debug windows.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
proteus-mcp
An MCP server that lets Claude (Opus 5.5) work inside Proteus 8.6: draw schematics around ICs such as the 8086, attach firmware, run the simulation and check the result.
The acceptance target is the YTU BLM3061 (Mikroişlemci Sistemleri ve Assembly Dili) lab set: given a lab's
tanım.pdf and its taslak.pdsprj, Claude should be able to produce a working .pdsprj and show that it meets
the "İstenenler" list.
Status: usable. Every 2025 Proteus lab and odev2 has been completed through these tools by a fresh Claude session (below). TODO.md records the work and what still needs the owner, docs/FORMAT.md the file format notes, docs/QUIRKS.md the Proteus and MASM quirks the tools work around.
Status
Working and tested through a real MCP client (scripts/smoke_mcp.py), on this machine:
open a lab project into a workspace copy, read and replace its 8086 source;
build the firmware with MASM 5.10 (headless DOSBox, about 1 s) and store it in the project;
launch Proteus, run, pause and stop the simulation, read the simulation log, take screenshots of the window, of instrument popups and of Debug popups (registers, memory, 8255 status);
get Proteus's own netlist and ask which pins are on a net;
edit schematics without the GUI: list parts and pins, wire two pins together, attach GND / power / named-net terminals, change properties and values. Edits are written straight into the project file and were confirmed in Proteus 8.6 (opened without new warnings, connections present in Proteus's netlist);
place new device types from the libraries, delete and move parts, change annotated parts (8086 clock, program file, values) through Proteus's own dialog, and render the sheet as an image to check the layout.
Proteus was reinstalled on 2026-11-15; simulation of the 8086 labs now works (the earlier install could not
drive 8086 I/O, see docs/QUIRKS.md).
Fresh-session test (the real acceptance check): a new Claude Opus 5.5 session, run headless with only
these tools and the Read tool and given just the lab's PDF path, completed lab5 (all 8 keys show their digit),
lab6 (8251 with a full 0158H decoder; DEF / NO / DEF on terminal 2), odev2 (ROM/RAM map; RAM shows the
PDF's bytes) and lab8 (interrupt-driven ADC samples printed in hex, changing with the pot) on its own, including exporting
the project and reporting how each requirement was checked. With only "do the lab in this PDF" as the prompt,
a session also finished lab7 (LDR-controlled motor speed) with no tool errors. Prompts: e2e/prompt_*.txt. The tool problems
those sessions reported are fixed. Run one yourself:
cd e2e
claude -p (Get-Content prompt_lab5.txt -Raw) --model claude-opus-5-5 --mcp-config mcp.json --strict-mcp-config `
--allowedTools "mcp__proteus__*" "Read" --disallowedTools advisorWorked example: scripts/lab5_example.py completes the 2025 lab5 template (8255 + 7-segment) entirely
through the MCP tools: address wiring, eight added series resistors, port A to the display, port B to the
buttons with pull-ups, a MASM 5.10 program, then 21 connectivity checks against Proteus's own netlist, all
passing, and the 8086 loading the new program. It then runs the simulation and presses the eight buttons;
the display shows 0 to 7 (docs/evidence/lab5_buttons.png).
scripts/lab6_example.py does lab6 (8251 USART): a full address decoder for 0158H/015AH built from the 74154,
two 74HC4078 and four NOT gates, the 8251 and terminal wiring, and the program. Typing the PDF's three
scenarios into terminal 1 prints DEFNODEF on terminal 2 (docs/evidence/lab6_terminals.png).
scripts/lab7_example.py does lab7 part 1 (DAC0830 at 200H, 100 Hz 32-sample sine): renames the YA1..YA6
placeholders, grounds the ADC pins the template leaves open, writes the program. Netlist checks pass and the
simulation runs cleanly. The DAC was checked with the template's voltmeter and a slowed copy of the program:
it follows the sine between 0 and 12 V (docs/evidence/lab7_dac_slow.png); the 100 Hz rate comes from the
cycle count. That was before the scope could be used (see Limitations); today the scope shows it directly.
scripts/lab8_example.py does lab8 (8259 + ADC0804 + 8251) starting from the bare template: replaces the
static POT with an interactive POT-HG, builds the 74154 decoder, wires 8259, 8251, ADC, terminal and two
9600 Hz clock generators, and writes an interrupt-driven program (vectors 51H/52H, edge triggered). The
terminal, switched to Hex Display Mode by the tool, shows the samples; turning the pot changes them
(e.g. 80 -> 66 -> 99, docs/evidence/lab8_pot_terminal.png).
scripts/odev2_example.py does odev2 (64 KB ROM at 20000H, 64 KB RAM at 60000H): two 74LS138 bank decoders
(even on A0, odd on /BHE), an OR gate placed from the library plus three copies and a NOT for the A15 split,
all ROM/RAM address, data and control lines, the ROM images copied with the project, and a program calling
the two FAR routines. Paused, RAM00 shows 34 / CD and RAM01 12 / AB (docs/evidence/odev2_ram.png).
scripts/scratch_example.py builds a circuit that is in no template. It starts from lab6, deletes its 8251
(an annotated part, so Proteus itself deletes it and the leftover terminals are tidied), places an 8255A and
a LED-RED from the libraries, copies the LED seven times, decodes the 8255 at 20H..26H with the 74154 and
writes 0A5H to port A. LEDs PA0, PA2, PA5 and PA7 light (docs/evidence/scratch_8255_leds.png).
Wires are routed by a grid maze router (route.py): it never passes through a part body, pin, wire end,
junction or terminal, never runs along an existing wire, and only crosses wires at right angles. Junction
taps, wire deletion and moving wired parts were checked in Proteus with scripts/smoke_junction.py (its own
netlist shows the intended nets; the file opens without a dialog).
Related MCP server: Altium MCP Server
Limitations
Verified on this machine (Proteus 8.6 SP2, build 23525) unless marked otherwise.
Scope: the Digital Oscilloscope works through the tools (2026-11-17): a 1 kHz generator on channel A of the 2025 lab7 solution draws its square wave and
screenshot(window="Oscilloscope")captures it (docs/evidence/scope_1khz.png). The scope's settings are part properties (CHAACDC,CHAVAL,HORIZVAL...) set withschematic_set_propertywhile Proteus is closed; a saved design may have its channels switched off.Bus wires are not drawn between pins. Buses are joined by named terminals (
AD0joins theAD[0..7]line) and wire labels, which is how the templates do it.Annotated parts (U1, R3, ...) keep their properties in ROOT.CDB, which only Proteus may write: offline edits are refused, and
proteus_edit_component(save=True)changes them through Proteus instead.New device types are placed through the Pick Devices dialog with the real mouse; button presses, the pot and terminal hex mode use it too. The user should not move the mouse while these run.
Firmware: 8086 programs only (MASM 5.10 in DOSBox). PIC/AVR HEX firmware is not handled (unverified, no lab needs it).
Generators are left out of Proteus's netlist (Proteus's behaviour);
net_ofadds them from the sheet.Only Proteus 8.6 project files (
FILEVER814) have been decoded. Other versions are untested; there is no explicit version check, so an edit on such a file may fail with a parse error.The plain assembly labs (1 to 4, odev1) are out of scope: they have no Proteus project.
Install
Requirements: Windows, Proteus 8.6 SP2, DOSBox 0.74-3 (for the assembler), and
uv, and MASM 5.10 (MASM.EXE and LINK.EXE, from the course materials).
MASM is Microsoft software and is not shipped with proteus-mcp; see Finding MASM.
uvx runs the server straight from GitHub; no venv to manage. Check the setup first:
uvx --from git+https://github.com/Xedygen/proteus-mcp proteus-mcp doctorEvery line should say True except labs_found (see below). From a local checkout use
--from D:\path\to\proteus-mcp instead; after changing the code, add --reinstall once so uvx rebuilds its
cached copy.
Finding MASM
The server looks for a folder holding both MASM.EXE and LINK.EXE, in this order:
the
PROTEUS_MCP_MASMenvironment variable;the location saved in
%LOCALAPPDATA%\proteus-mcp\config.json;tools\masm\in a source checkout (ignored by git);a search of
C:\masm,C:\MASM510and similar, then three folder levels below your home folder (Desktop, Downloads, Documents, OneDrive) and each drive root. This takes well under a second, and the folder it finds is saved, so the search runs once.
If none of these finds it, firmware_build says so and Claude asks you where the folder is, then saves it with
the masm_location tool. You can also tell Claude the folder at any time, or set PROTEUS_MCP_MASM.
Where things live when installed:
What | Default | Override |
Proteus |
|
|
DOSBox |
|
|
MASM 5.10 | found as above |
|
Workspace (project copies) |
|
|
Lab folders for |
|
|
Run from a source checkout (python -m proteus_mcp), the workspace and labs are work\ and labs\ in the
repo instead. lab_list is a convenience; project_open takes any .pdsprj path.
Proteus runs visibly on the desktop. sim_click, terminal_mode and schematic_place_devices move the
real mouse, so leave it alone while they run. (PROTEUS_MCP_BACKGROUND=1 hides Proteus off-screen; it was a
development aid, and the oscilloscope does not draw there.)
Connect a client
Claude Code (add --scope user to have it in every project):
claude mcp add proteus -- uvx --from git+https://github.com/Xedygen/proteus-mcp proteus-mcpClaude Desktop, in %APPDATA%\Claude\claude_desktop_config.json, then restart Claude Desktop:
{
"mcpServers": {
"proteus": {
"command": "uvx",
"args": ["--from", "git+https://github.com/Xedygen/proteus-mcp", "proteus-mcp"]
}
}
}If Claude Desktop cannot find uvx, use its full path (where uvx, usually
C:\Users\<you>\.local\bin\uvx.exe). The first start downloads the dependencies and takes a few seconds.
Tools
Tool | What it does |
| Install, versions, DOSBox and MASM, running Proteus processes |
| Where MASM 5.10 is; with a path, checks and remembers it |
| Rules for code that builds and simulates here (MASM 5.10 limits, model quirks) |
| Workspace copies, one folder per project under |
| Read |
| One Proteus instance at a time, only one this server started |
|
|
| Main window or a named window; Debug-menu popups while paused (memory popups scrolled to an |
| The whole sheet rendered by Proteus's Export Bitmap at 100 to 600 DPI (sharp at any zoom), optionally cropped and saved |
| A memory popup (8086 Memory Dump, a RAM/ROM part's Memory Contents) as hex rows from any address, through the popup's own Copy All (checked on odev2: RAM00 34/CD) |
| Press a button / toggle a switch during a run (real mouse, guarded); close-up of one part |
| Type into Virtual Terminals during a run; capture what they show |
| Offline search of the installed device libraries (about 55,000 devices: name, library, category, description), e.g. "4-to-16 decoder" |
| Place new device types from the Proteus libraries (GUI, then saved by Proteus); unknown names, spots outside the sheet border or on an existing part or wire are refused before Proteus starts |
| Development aid, off by default: hides Proteus off-screen (mouse-based tools then refuse) |
| Proteus's own connectivity (Netlist Compiler, logical mode) |
| Parts, values, properties, pins with grid positions and connection state (unannotated parts as |
| Orthogonal wire between two unconnected pins, e.g. |
| Wire a free pin onto an existing net (a wired pin, terminal or wire label) with a junction dot |
| Delete the wire on a pin or at a point; a junction left with two wires is merged away |
| Place a copy of a part already in the design (e.g. a resistor or a 74HC373) with its own reference, optionally rotated or mirrored |
| GND, power or named-net terminal on a pin ( |
| Name a net with a wire label; wires and terminals with the same name are one net (the label is placed clear of pins and of bodies estimated from pin positions; a body that extends past its pins, like the 7-segment display, can still be overlapped, so pass |
| Rename terminals / wire labels (e.g. lab7's YA1..YA6) |
| Properties / value of unannotated parts, offline (annotated ones live in ROOT.CDB: use |
| Digital clock generator on a pin, e.g. 9600 Hz on the 8251's TxC/RxC |
| Delete a part or generator with its wires (annotated parts such as an 8251 are deleted by Proteus itself, then the terminals, generators and junctions left at the far ends are tidied); move a part, dragging its wires along (re-routed where needed) |
| Virtual Terminal options during a run, e.g. Hex Display Mode (real mouse) |
| Lab folders with their PDF, template and reference solutions |
| Offline list of net names (terminals, wire labels) and the pins wired to them |
| Offline: unconnected pins per part, terminals whose partner is missing or misspelled, parts outside the sheet border (they simulate but cannot be seen or clicked) |
| Click a button in a Proteus dialog the server does not answer itself |
| Change any part's properties or value (annotated too, e.g. the 8086 clock, |
Use it on a lab PDF
Connect the server to Claude Code or Claude Desktop (above) and restart the client;
/mcpin Claude Code or the tools icon in Desktop should listproteus.Leave Proteus closed; the server starts its own instance. Mouse-based steps (placing new device types, pressing buttons, the pot, terminal hex mode) move the real mouse; leave it alone while they run.
Attach the lab's
tanım.pdfto the chat (Desktop: drag it in; Claude Code: give its path) and ask, e.g.:"Use the proteus tools to do this lab. Find its template with lab_list, read quirks() first, wire what the PDF asks for, write and build the 8086 program, simulate it, show me evidence that every item of İstenenler works, and export the finished project to D:\Odev\lab8.pdsprj."
The finished project is a normal .pdsprj; open it in Proteus to look at or present it.
What is in this folder
Path | Contents |
| This file |
| MIT licence |
| Work order by milestone, and things needed from the owner |
| What is known about the Proteus 8.6 project file format |
| Proteus, model and MASM 5.10 quirks (also served by the |
| Screenshots from the worked examples |
| The server package |
| Tests that run without Proteus ( |
| Worked lab examples, smoke tests, lab download and sample extraction |
| Prompts and client config for the fresh-session acceptance runs |
| Optional local MASM 5.10 copy for development (not in git) |
| Lab material pulled from the YTU archive repo (not in git) |
labs/ is a copy of
lablar/
from the archive. It holds the assignment PDFs, the instructor templates (taslak.pdsprj, proteus_sablon.pdsprj)
and past student solutions. Re-create it with python -X utf8 scripts/pull_labs.py labs get.
The target labs
Proteus-based assignments (these are what the MCP must handle):
Lab | Topic | Parts | What "working" looks like |
2025 lab5 | 8255 + 7-segment | 8086, 74HC373, 8255A, common-anode 7-seg, 8 buttons, resistors | Pressing button N shows digit N |
2025 lab6 | 8251 USART | 8086, 3x 74273, 74154, 8251A, 2 virtual terminals, gates | Type |
2025 lab7 | DAC0830 / ADC0804 | 8086, latches, 74154, DAC0830, op-amp, scope (plus ADC, LDR, motors for part 2) | 100 Hz, 32-step sine on the scope; or motor speed follows the LDR |
2025 lab8 | 8259 + ADC0804 + 8251 | 8086, 3x 74273, 74154, 8251A, 8259, ADC0804, pot, virtual terminal | Five ADC samples printed as hex bytes, interrupt driven (vectors 51H, 52H) |
2025 odev2 | Memory map and address decoding | 8086, 3x 74273, 2x 74LS138, 4x 27C128, 2x 62256 | ROM at 20000H, RAM at 60000H, RAM00/RAM01 show the bytes written by the ROM routines |
2024 lab 5 to 8 | Same family of topics | Templates and solutions included | Extra test cases; lab 5 (8255 password, 7-segment) and lab 8 (DAC waveforms) done by fresh sessions |
Labs 1 to 4 and odev1 (both years) ship only .asm / .cpp files and no Proteus project. They are plain
assembly exercises with no circuit, so they are out of scope (decided in TODO.md);
firmware_build still assembles them.
Two things stand out across all of them:
Every Proteus lab starts from a template where the parts are already placed. The work is wiring, net labels, address decoding logic, part properties and the assembly program. Drawing from a blank sheet is rarely needed.
The result is checked by looking: a 7-segment digit, virtual terminal text, a scope trace, a memory window. The MCP needs a way to read those back, not only to start the simulation.
What this machine has
Item | Finding |
Proteus | 8.6 SP2, build 8.6.23525, at |
8086 model | Present ( |
Device libraries | 162 |
8086 assembler | MASM 5.10 ( |
DOSBox | 0.74-3 at |
Proteus's own Build button | Will not work: it expects MASM32 ( |
Python / uv / Node | Python 3.10.11, |
How a Proteus 8.6 project is stored
A .pdsprj is a ZIP archive. Lab 5's template contains:
Entry | Format | Role |
| XML | Version stamp ( |
| Binary ( | The drawing: parts, wires, labels, positions |
| Binary with plain-text properties | Parts database: pins, nets, properties such as |
| XML | VSM Studio firmware project (compiler MASM32) |
| Text | The assembly source |
| DOS EXE | The built firmware the 8086 model loads |
So the firmware half is easy to edit from outside Proteus (text and XML in a ZIP). The schematic half is a binary
format with no public specification, and ROOT.DSN and ROOT.CDB must stay consistent with each other.
Proteus 8.6 has no official automation API.
Prior art
Repo | How it works | Why it was not used as is |
Writes | Proteus 9 containers only ( | |
Drives the Proteus window through UI Automation | Cannot draw schematics; its menu-driven simulation control and Edit Component approach carried over (no code copied) |
How it works
Python MCP server over stdio (official mcp SDK, managed with uv), Windows only. Three layers:
Project files, offline. A
.pdsprjis opened as a ZIP in a workspace copy;dsn.pyparses and rebuilds ROOT.DSN byte for byte,schematic.pyedits it (wires from a grid maze router, terminals, labels, part copies, generators) andnetlist.pyreads Proteus's own netlist. Templates are never written.Firmware. The 8086 source is assembled with the course's MASM 5.10 in headless DOSBox and the DOS EXE is stored where the project's firmware entry expects it.
Proteus GUI.
gui.pystarts its own Proteus instance and drives it through menu commands and dialogs: simulation control, logs, Export Bitmap sheet images, Debug popups read as text, Edit Component, Pick Devices, button presses and terminal typing. Unknown dialogs are reported, never clicked through.
Results are checked against Proteus itself: its netlist for connectivity, its simulation log for the loaded program, and images or popup text for what the circuit does.
Licence
proteus-mcp is released under the MIT licence.
It does not include or redistribute any third-party software or course material:
Proteus is commercial software by Labcenter Electronics. You need your own licensed copy; proteus-mcp drives it the way a user would and does not modify or patch it.
MASM 5.10 and LINK are Microsoft software. They are not shipped; the server uses the copy you already have (see Finding MASM).
DOSBox is GPL software installed separately; proteus-mcp only starts it as an external program.
Lab material (
labs/) is downloaded byscripts/pull_labs.pyfrom a public archive repository for local testing and is not part of this repository.Python dependencies (mcp, pywinauto, pywin32, Pillow) are installed from PyPI under their own permissive licences (MIT, BSD-3-Clause, PSF, MIT-CMU).
Proteus and Labcenter are trademarks of Labcenter Electronics Ltd; MASM is a trademark of Microsoft Corporation. This project is not affiliated with or endorsed by either.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Design circuits, simulate and verify embedded firmware, and lay out PCBs with AI agents.
Edit AutoCAD and Revit MEP drawings from Claude or ChatGPT in plain English.
Design, route, check, review and export manufacturable PCBs from plain language; KiCad import.
Build, check and open Arduino, ESP32 and Pico circuits with code in the Mokxi simulator.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceUse Claude to control or ask questions about your Altium project.228MIT
- AlicenseNot gradedqualityDmaintenanceUse Claude to control or ask questions about your Altium project.MIT
- AlicenseCqualityBmaintenanceEnables Claude Code to directly operate 嘉立创EDA Professional for reading PCB/schematic designs, moving components, routing tracks, placing vias, pouring copper, running DRC, and managing silkscreens via natural language.391MIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude to open, build, edit, solve, and report on DWSIM 9.0.5 process simulations, either live in a DWSIM window or in a hidden background copy.MIT