Kepler Formal Testing Agent Setup Guide

This guide explains how to clone and configure the two repositories you asked for:

• https://github.com/najaeda/naja-agent
• https://github.com/keplertech/kepler-formal-mcp

What this setup does

This setup gives Claude an end-to-end automation workflow for formal and netlist tasks:

1. Claude can automatically create Naja scripts (based on the Naja skill).
2. Scripts are written into your shared MCP folder (shared_files server).
3. Claude executes those scripts through an MCP command runner (desktop-commander).
4. The generated outputs (edited netlists, reports, transformed designs) are read back from the shared folder.
5. Claude can then call Kepler Formal MCP to analyze or validate the result.

In short, this turns Claude into an automated loop:

• generate script -> run script -> inspect output -> verify with Kepler Formal

That is why both parts are needed:

• Naja side: script generation and netlist transformation
• Kepler Formal side: formal-oriented checking and result analysis

The setup steps below are aligned with the local documentation available in this workspace from:

• kepler-formal-mcp/README.md
• kepler-formal-mcp/docs/instructions-claude.md
• naja-agent/README.md
• naja-agent/docs/setup.md

1. Clone both repositories

mkdir -p ~/mcp-workspace
cd ~/mcp-workspace

git clone --recurse-submodules https://github.com/najaeda/naja-agent.git
git clone --recurse-submodules https://github.com/keplertech/kepler-formal-mcp.git

If you already cloned without submodules:

cd ~/mcp-workspace/naja-agent
git submodule update --init --recursive

cd ~/mcp-workspace/kepler-formal-mcp
git submodule update --init --recursive

2. Build Kepler Formal MCP

From kepler-formal-mcp:

cd ~/mcp-workspace/kepler-formal-mcp
./build_kepler_formal.sh

If you want automatic dependency installation first:

./build_kepler_formal.sh --install-deps

On Ubuntu/Debian, the local Kepler docs list these dependencies:

sudo apt-get update
sudo apt-get install -y \
	g++ libboost-dev python3.9-dev capnproto libcapnp-dev libtbb-dev \
	pkg-config bison flex doxygen libspdlog-dev libfmt-dev \
	libboost-iostreams-dev zlib1g-dev cmake git

Build output is generated under:

• thirdparty/kepler-formal/build/

3. Prepare the Naja side (from local naja-mcp docs)

Based on local naja-mcp docs, the current workflow is centered on a Naja skill package plus MCP helpers for file access and command execution.

Install Naja EDA Python package first:

python3 -m pip install najaeda

3.1 Package the Naja skill

1. Zip the naja-base folder with its internal structure unchanged.
2. Keep SKILL.md at the top level inside that zipped folder structure.

Expected source folder in this workspace:

• naja-mcp/skills/naja-base/

3.2 Add the skill in Claude

1. Open Claude.
2. Go to Customize -> Skills.
3. Click +.
4. Select Create.
5. Upload the ZIP file.

4. Configure Claude Desktop MCP entries

Open your Claude Desktop config file:

• Linux/macOS: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\\Claude\\claude_desktop_config.json

Add Kepler Formal MCP server:

{
	"mcpServers": {
		"kepler-formal": {
			"command": "python3",
			"args": [
				"/home/<user>/mcp-workspace/kepler-formal-mcp/server.py"
			],
			"env": {
				"PYTHONPATH": "/home/<user>/mcp-workspace/kepler-formal-mcp/thirdparty/kepler-formal/src"
			}
		}
	}
}

Add the MCP helpers recommended by local naja-mcp/docs/setup.md:

{
	"mcpServers": {
		"shared_files": {
			"command": "npx",
			"args": [
				"-y",
				"@modelcontextprotocol/server-filesystem",
				"/home/<user>/shared-mcp-files"
			]
		},
		"desktop-commander": {
			"command": "npx",
			"args": [
				"-y",
				"@wonderwhy-er/desktop-commander@latest"
			]
		}
	}
}

Merge entries into a single valid JSON object under the same mcpServers key.

5. Verify

1. Save the config.
2. Restart Claude Desktop.
3. Confirm Kepler and helper MCP entries are connected.
4. Confirm the Naja skill appears in Claude Skills.

Troubleshooting

• Always use absolute paths.
• If python3 is not found, use /usr/bin/python3.
• If config fails to load, validate JSON syntax.
• If Kepler build fails, re-run submodule init and re-check system dependencies.