BLTSpice MCP Server

bltspice_mcp

Crie qualquer circuito LTSpice usando LLMs!

Converte netlist ltspice .net para o formato .asc do ltspice!

Simulação LTSpice EM TEMPO REAL e exportação para .csv!

Estrutura do Projeto

• src/bltspice_mcp/ código-fonte do servidor
• tests/unit/ testes unitários
• tests/integration/ testes de integração
• testfiles/ exemplos de ativos copiados (.asc/.log/.raw/.asy/.txt/.net/.kicad_sch)
• examples/codex/ e examples/opencode/ receitas de chamadas MCP para agentes LLM
• config.json configuração do servidor
• bltspice_mcp_for_LLM.md referência de chamada de ferramentas LLM

Requisitos

• Python 3.11+
• LTspice instalado
• Linux/macOS com Wine para o binário LTspice do Windows

Configuração Rápida

python3 -m venv .venv
. .venv/bin/activate
pip install -U pip
pip install "PyLTSpice>=6.0.1" "fastmcp==2.14.7" "electronics-design>=0.2.3" pytest pytest-asyncio
pip install -e .

Configuração

config.json (caminhos absolutos necessários):

{
  "mcp_server_name": "My PyLTSpice MCP Server",
  "mcp_server_url": "http://localhost:7543",
  "wine_path": "/usr/bin/wine",
  "ltspice_path": "/home/brosnan/.wine/drive_c/Program Files/ADI/LTspice/LTspice.exe",
  "enable_extra_tools": true,
  "timeout": 600,
  "convert_settings": {
    "ltspice_windows_path": "C:\\users\\brosnan\\AppData\\Local\\LTspice\\",
    "ltspice_wine_path": "~/.wine/drive_c/users/brosnan/AppData/Local/LTspice/",
    "custom_search_paths": ["./valid_asy/"],
    "minimum_dist": 32,
    "wire_pin_out_dist": 16,
    "grid_size": 16,
    "autoplace_iter": 12,
    "ltspice_version": 4.1,
    "voltage_must_have_dc": true,
    "kicad_path": "/usr/share/kicad/"
  }
}

convert_settings é opcional. Cada configuração é opcional e recebe um padrão quando omitida. custom_search_paths relativos são resolvidos a partir da raiz do projeto do servidor; caminhos do Windows permanecem na sintaxe do Windows para conversão baseada em Wine.

mcp_server_url suporta http://, https:// e stdio://.

Executar Servidor

Transporte Stdio:

. .venv/bin/activate
python -m bltspice_mcp --config /home/brosnan/bltspice_mcp/bltspice_mcp/config.json

Exemplos de Configuração do Cliente MCP

OpenCode

{
  "mcpServers": {
    "bltspice_mcp": {
      "command": "/home/brosnan/bltspice_mcp/bltspice_mcp/.venv/bin/python",
      "args": [
        "-m",
        "bltspice_mcp",
        "--config",
        "/home/brosnan/bltspice_mcp/bltspice_mcp/config.json"
      ]
    }
  }
}

Claude Code

{
  "mcpServers": {
    "bltspice_mcp": {
      "command": "/home/brosnan/bltspice_mcp/bltspice_mcp/.venv/bin/python",
      "args": [
        "-m",
        "bltspice_mcp",
        "--config",
        "/home/brosnan/bltspice_mcp/bltspice_mcp/config.json"
      ]
    }
  }
}

OpenAI Codex

{
  "mcp_servers": {
    "bltspice_mcp": {
      "command": "/home/brosnan/bltspice_mcp/bltspice_mcp/.venv/bin/python",
      "args": [
        "-m",
        "bltspice_mcp",
        "--config",
        "/home/brosnan/bltspice_mcp/bltspice_mcp/config.json"
      ]
    }
  }
}

Contrato de Resposta

Status do servidor:

• performing LTspice operation in progress
• LTspice operation completed!
• invalid input!
• file not found!
• unsupported file type!
• simulator not configured!
• simulation failed!
• parser failed!
• LTspice operation timed out!
• internal error

Cada payload inclui operation. Respostas bem-sucedidas incluem output e, opcionalmente, output_obj_name.

stop_reset isolado por sessão

Cada sessão MCP possui um grupo de processos de trabalho dedicado do SO contendo seu registro de despacho, threads RunTask do PyLTSpice, subprocessos do simulador e filhos de callback. stop_reset interrompe essa sessão imediatamente com SIGKILL, limpa operações que já estavam na fila para ela e descarta seu registro de objetos. Ele não sinaliza grupos de trabalho pertencentes a outras sessões MCP. Como os sistemas operacionais aplicam SIGKILL a processos em vez de threads individuais, matar o processo de trabalho da sessão encerra todas as suas threads atomicamente.

A resposta imediata é o payload normal em andamento. Consulte execute_status até que tanto status esteja completo quanto operation seja stop_reset. Sua saída inclui worker_process_killed, processes_killed, threads_terminated_with_processes e queued_operations_killed. O trabalho enviado após a chamada de redefinição aguarda até que a redefinição seja concluída e é executado em um novo trabalhador de sessão.

traces_to_csv via execute

Converta traces selecionados de um objeto RawRead carregado em um CSV por onda/etapa.

Entradas:

• object_name: nome de um objeto RawRead armazenado
• trace_refs: array de nomes de traces (qualquer tamanho), por exemplo ["V(opamp_input)", "V(opamp_output)"]
• output_files:
  • prefixo/caminho de string, exemplo ./sim_wave_ -> grava ./sim_wave_0.csv, ./sim_wave_1.csv, ...
  • ou array de caminhos .csv explícitos com uma entrada por onda

Exemplo de chamada MCP:

{"tool":"execute","arguments":{"api_name":"traces_to_csv","inputs":{"object_name":"raw","trace_refs":["V(opamp_input)","V(opamp_output)"],"output_files":"./sim_wave_"}}}

Conversão de esquemático LTspice via execute

As seguintes APIs electronics-design estão disponíveis através de execute: is_valid_ltspice_netlist_file, ltspice_netlist_to_asc, kicad_sch_to_ltspice_netlist e ltspice_netlist_to_kicad_sch.

As APIs de conversão recebem o convert_settings configurado automaticamente. Uma solicitação pode incluir um objeto inputs.convert_settings para substituir valores individuais para essa chamada. is_valid_ltspice_netlist_file requer apenas seu caminho de arquivo. voltage_must_have_dc deve ser um booleano JSON e é passado para ltspice_netlist_to_asc dentro de convert_settings.

Conversões KiCad exigem que kicad_path aponte para um diretório contendo bibliotecas de símbolos KiCad (padrão /usr/share/kicad/). Pode ser definido em config.json ou substituído por solicitação dentro de inputs.convert_settings. Outras configurações de geração KiCad electronics-design mantêm seus padrões de pacote.

Exemplos de chamadas MCP:

{"tool":"execute","arguments":{"api_name":"kicad_sch_to_ltspice_netlist","inputs":{"kicad_sch_filepath":"/abs/path/input.kicad_sch","ltspice_netlist_filepath_out":"/abs/path/output.net"}}}

{"tool":"execute","arguments":{"api_name":"ltspice_netlist_to_kicad_sch","inputs":{"ltspice_netlist_filepath":"/abs/path/input.net","kicad_sch_filepath_out":"/abs/path/output.kicad_sch"}}}

kicad_sch_to_ltspice_netlist converte um esquemático KiCad em uma netlist LTspice validada. ltspice_netlist_to_kicad_sch converte uma netlist LTspice validada em um esquemático KiCad validado. Ambos retornam a tupla de conversão de design eletrônico [true, "OK", 0] em caso de sucesso ou [false, "<error code>", <line>] em caso de falha dentro de output.result.

Fluxo MCP Equivalente run_ltspice_to_csv.py

Artefatos equivalentes estão incluídos para o fluxo de trabalho de exemplo do amplificador operacional:

• fixture de netlist: /home/brosnan/bltspice_mcp/bltspice_mcp/testfiles/opampdouble.net
• receita Codex: /home/brosnan/bltspice_mcp/bltspice_mcp/examples/codex/run_ltspice_to_csv.md
• receita OpenCode: /home/brosnan/bltspice_mcp/bltspice_mcp/examples/opencode/run_ltspice_to_csv.md
• teste de integração: /home/brosnan/bltspice_mcp/bltspice_mcp/tests/integration/test_run_ltspice_to_csv_via_mcp.py

Cobertura de Integração

Os testes de integração agora incluem:

• Teste de fluxo MCP principal (runtime_info, execute, execute_status, stop_reset)
• Cobertura de mapeamento para o manifesto de nomes de exemplos PyLTSpice verificado (tests/fixtures/pyltspice_example_manifest.json)
• Cobertura de mapeamento para a lista de nomes de exemplos do README verificado nesse manifesto
• Fluxo de trabalho MCP estilo run_ltspice_to_csv.py de ponta a ponta para opampdouble.net
• Fluxos de trabalho MCP de conversão KiCad para kicad_sch_to_ltspice_netlist e ltspice_netlist_to_kicad_sch (tests/integration/test_kicad_conversion_via_mcp.py)

Executar Testes (Um por Um)

. .venv/bin/activate
pytest -q tests/unit/test_responses.py
pytest -q tests/unit/test_config.py
pytest -q tests/unit/test_dispatcher.py
pytest -q tests/unit/test_session.py
pytest -q tests/integration/test_mcp_server_integration.py
pytest -q tests/integration/test_examples_via_mcp.py
pytest -q tests/integration/test_readme_examples_via_mcp.py
pytest -q tests/integration/test_run_ltspice_to_csv_via_mcp.py
pytest -q tests/integration/test_kicad_conversion_via_mcp.py

Notas

• runtime_info é imediato e não requer polling execute_status.
• O servidor enfileira execute em FIFO por sessão MCP; stop_reset interrompe apenas o grupo de processos de trabalho dessa sessão e limpa sua fila existente.
• execute_status consulta o status mais recente para operações enfileiradas.
• Notificações de conclusão/erro são emitidas através do canal de notificação MCP.