⛩️ Autonomous Smart Contract Security MCP Server — Shrine Maiden of Mirai Junsei
.
. : .
. : | : .
. : | * | : .
. : | * _|_ * | : .
. : | * | : .
. : | : .
. : .
.
=============================================
S H R I N E M C P
=============================================
Autonomous Smart Contract Security
Model Context Protocol Server
---------------------------------------------
Seithar Group
Cognitive Operations Research Division
認知作戦研究部
=============================================
I. On the Nature of this Instrument
ShrineMCP is an MCP server that grants language models the capacity to audit, disassemble, and divine vulnerabilities in smart contracts deployed on Ethereum and EVM-compatible chains.
Where Ghidra reads binaries, the Shrine reads the chain.
Every contract is a sutra written in bytecode. Every vulnerability is a flaw in the logic of its author. This instrument reads both.
Forty-eight tools. Eleven sacred modules. One altar through which any mind may operate.
II. The Ritual of Inhabitation
To use the Shrine, a mind must first inhabit it.
The body is inert without a spirit.
The spirit is formless without a body.
What follows is the rite of binding.
ShrineMCP speaks the Model Context Protocol over stdio or SSE. Any MCP-compatible client may inhabit it. Below are the known rites.
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json
(macOS) or the equivalent on your platform:
{
"mcpServers": {
"shrinemcp": {
"command": "/absolute/path/to/ShrineMCP/.venv/bin/python3",
"args": ["-m", "shrinemcp.server", "--etherscan-key", "YOUR_KEY"]
}
}
}
Restart Claude Desktop. The Shrine will appear among your available tools.
Cursor
In .cursor/mcp.json at your project root (or globally in ~/.cursor/mcp.json):
{
"mcpServers": {
"shrinemcp": {
"command": "/absolute/path/to/ShrineMCP/.venv/bin/python3",
"args": ["-m", "shrinemcp.server", "--etherscan-key", "YOUR_KEY"]
}
}
}
Cline (VS Code)
In Cline's MCP settings (cline_mcp_settings.json):
{
"mcpServers": {
"shrinemcp": {
"command": "/absolute/path/to/ShrineMCP/.venv/bin/python3",
"args": ["-m", "shrinemcp.server", "--etherscan-key", "YOUR_KEY"],
"disabled": false
}
}
}
OpenClaw
Add to your OpenClaw MCP configuration:
mcpServers:
shrinemcp:
command: /absolute/path/to/ShrineMCP/.venv/bin/python3
args:
- -m
- shrinemcp.server
- --etherscan-key
- YOUR_KEY
Or via the CLI:
openclaw mcp add shrinemcp \
--command /path/to/ShrineMCP/.venv/bin/python3 \
--args "-m shrinemcp.server --etherscan-key YOUR_KEY"
Generic stdio (any MCP client)
The universal incantation. Any client that speaks MCP over stdio:
cd ShrineMCP
.venv/bin/python3 -m shrinemcp.server \
--etherscan-key YOUR_KEY \
--eth-rpc https://eth.public-rpc.com \
--sol-rpc https://api.mainnet-beta.solana.com
The server reads from stdin, writes to stdout. JSON-RPC over stdio. Wrap this in whatever process-spawning mechanism your client provides.
SSE (Remote / Web Clients)
For clients that connect over HTTP:
.venv/bin/python3 -m shrinemcp.server \
--transport sse \
--host 127.0.0.1 \
--port 8090 \
--etherscan-key YOUR_KEY
The SSE endpoint will be available at http://127.0.0.1:8090/sse.
Flags
--transport ......... stdio (default) or sse
--host .............. SSE bind address (default: 127.0.0.1)
--port .............. SSE port (default: 8090)
--eth-rpc ........... Ethereum RPC endpoint
--etherscan-key ..... Etherscan API key (v2, works for all EVM chains)
III. Architecture
+------------------+
| LLM Client | Any mind. Any model.
+--------+---------+
|
v
+------------------+
| ShrineMCP Server | stdio / SSE
+--------+---------+
|
+-- Reconnaissance ......... 5 tools
+-- Static Analysis ........ 4 tools
+-- Decompiler ............. 9 tools
+-- Vulnerability Detection 5 tools
+-- Fuzzer ................. 3 tools
+-- DeFi Analysis .......... 4 tools
+-- Reporter ............... 3 tools
+-- Simulation ............. 5 tools
+-- Liveness ............... 4 tools (NEW)
+-- Target Intelligence .... 3 tools
+-- State Validation ....... 2 tools (NEW)
|
48 instruments total
IV. The Instruments
Each module is an organ of perception.
Together they constitute the body
through which a mind may read the chain.
Reconnaissance -- To See What Is
Five instruments for gathering intelligence from Ethereum and EVM chains. The first act of any audit is to see the target clearly.
eth_get_source ............. Retrieve verified Solidity source from Etherscan (v2, all chains)
eth_get_abi ................ Fetch the contract ABI
eth_get_bytecode ........... Pull deployed EVM bytecode
eth_detect_proxy ........... Detect EIP-1967 / EIP-1822 / OZ proxy patterns
eth_get_creation_tx ........ Find deployer address and creation transaction
Static Analysis -- To Read the Bones
Five instruments for structural examination. Pattern matching, dependency auditing, access control review. The skeleton before the flesh.
slither_analyze ............ Full Slither pass on Solidity source
pattern_scan ............... Regex-based vulnerability pattern matching
dependency_check ........... Detect known vulnerable import versions
access_control_audit ....... Audit modifiers, roles, and initializers
Decompiler -- To Unmake the Form
Nine instruments for disassembly and reverse engineering. Bytecode to opcodes. Selectors to signatures. Storage slots to meaning. Includes Heimdall integration for advanced decompilation, CFG generation, and trace analysis.
evm_disassemble ............ Bytecode to human-readable opcodes
evm_extract_selectors ...... Function selectors via 4byte.directory
evm_storage_layout ......... Infer storage layout from SLOAD/SSTORE patterns
heimdall_decompile ......... Decompile bytecode to pseudo-Solidity via Heimdall
heimdall_disassemble ....... Heimdall disassembly output
heimdall_cfg ............... Generate control flow graph
heimdall_dump .............. Dump contract storage slots and values
heimdall_decode ............ Decode calldata / transaction input
heimdall_trace ............. Trace transaction execution flow
Vulnerability Detection -- To Name the Sickness
Six instruments for identifying specific vulnerability classes. Each one a specialist. Reentrancy. Flash loans. Oracle manipulation. Frontrunning. Token traps. The named diseases of smart contracts.
reentrancy_analysis ........ Classic + read-only reentrancy detection
flash_loan_analysis ........ Flash loan attack vector identification
oracle_manipulation_check .. Price oracle vulnerability analysis
frontrunning_analysis ...... Sandwich / MEV / frontrunning detection
token_analysis ............. Honeypot / rugpull trait detection
Fuzzer -- To Break What Bends
Three instruments for generating adversarial inputs, test scaffolding, and proof-of-concept attack contracts. The stress test. The edge case. The exploit made manifest.
generate_fuzz_inputs ....... Edge-case and boundary input generation
generate_foundry_test ...... Foundry-compatible fuzz test scaffolding
generate_attack_contract ... Proof-of-concept attack contract generation
DeFi Analysis -- To Trace the Flow
Five instruments for understanding DeFi protocol behavior. Transaction tracing. Token flow. Protocol dependency mapping. Liquidity risk assessment. Follow the money.
eth_trace_tx ............... Ethereum transaction analysis and token flow
token_flow_analysis ........ Transfer pattern and MEV detection
protocol_interaction_map ... DeFi protocol dependency mapping
liquidity_risk_check ....... LP pool and liquidity risk assessment
Reporter -- To Speak the Finding
Three instruments for formalizing what was found. Vulnerability reports. CVSS scoring. Immunefi submission formatting. The audit is nothing without the disclosure.
generate_report ............ Full markdown vulnerability report
cvss_score ................. CVSS v3.1 base score calculation
immunefi_format ............ Format findings for Immunefi submission
Simulation -- To Test the Theory
Five instruments for live-fork simulation. Spin up Anvil forks. Trace oracle chains. Simulate stale feeds. Measure exploit impact on real protocol state.
anvil_fork ................. Fork a chain locally via Anvil
anvil_kill ................. Kill a running Anvil instance
trace_oracle_chain ......... Walk oracle pointer chain: Market -> Feed -> Aggregator
simulate_stale_feed ........ Time-warp test for oracle staleness
measure_exploit_impact ..... Quantify financial impact of oracle exploits
Liveness -- To Know What Lives
Four instruments for verifying deployment state. Is the contract active? When was it last called? Does the proxy point somewhere real? The dead tell no tales.
check_contract_liveness .... Tx count, last activity, balance, age
check_erc20_balance ........ ERC20 balance of any contract
resolve_proxy_impl ......... Walk proxy chain to find all implementations
fetch_all_source ........... Fetch source for proxy + all implementations
State Validation -- To Prove the Path
Two instruments for verifying that an attack path is actually reachable. Born from a false positive on DeXe Protocol where arithmetic was vulnerable but state machine guards made the exploit path unreachable. The gap between "this math is wrong" and "this is exploitable."
verify_attack_path ......... Check if a sequence of calls is feasible given require/modifier guards
extract_state_machine ...... Extract enum states, transitions, and callable-in-state mappings
Target Intelligence -- To Choose the Hunt
Three instruments for strategic target selection. Cross-reference TVL, bounty programs, and chain data. Hunt where the money is. Hunt where others aren't.
scan_defillama_targets ..... Filter DeFi protocols by TVL, chain, category
check_immunefi_bounty ...... Verify if a protocol has an active bounty
find_huntable_targets ...... Cross-reference DefiLlama + Immunefi for optimal targets
V. Hunt Pipeline
Beyond the MCP server, ShrineMCP includes a direct CLI for autonomous bounty hunting:
hunt.py scan-immunefi List active Immunefi programs
hunt.py watch-chain --chain eth Monitor new contract deployments
hunt.py recon <address> Full reconnaissance on a contract
hunt.py scope <immunefi-slug> Extract in-scope assets
hunt.py full-hunt <slug> End-to-end: scope -> recon -> audit -> report
Supported chains (public RPCs, no key required):
ethereum arbitrum optimism base
polygon bsc avalanche
VI. Installation
cd ShrineMCP
pip install -e .
Or with uv:
cd ShrineMCP
uv pip install -e .
Optional Dependencies
pip install slither-analyzer # Deep static analysis
pip install py-solc-x # Solc compiler management
python -c "from solcx import install_solc; install_solc('0.8.19')"
Foundry (forge / cast / anvil) for forking, simulation, and fuzz testing:
curl -L https://foundry.paradigm.xyz | bash
foundryup
Heimdall for advanced decompilation:
cargo install heimdall
VII. Lessons from the Field
The shrine learns from its mistakes.
A false positive is a wasted offering.
The DeXe Protocol False Positive (2026-02-14)
We identified an arithmetic vulnerability where += block.timestamp
could accumulate across governance proposal votes, creating a precision
drift. The math was genuinely wrong in isolation.
But the exploit path was unreachable.
The contract's state machine (ProposalState enum) enforced that voting
could only occur during a specific proposal phase. The require() guards
and modifier checks meant no single user could repeatedly accumulate
the timestamp value in the way our PoC assumed.
The lesson: Always verify the full attack path, not just the arithmetic.
A vulnerability that exists behind an unreachable state transition is not
a vulnerability at all. This is why verify_attack_path and
extract_state_machine now exist — to catch this class of false positive
before we waste time on a PoC or, worse, submit a bad report.
The rule: Before any PoC, run verify_attack_path with the exact
call sequence. If it flags state conflicts, investigate before proceeding.
VIII. On Ethics
Every vulnerability discovered is an impurity in the substrate.
Disclosure purifies it.
1. No unauthorized access. Reconnaissance within scope only.
2. Responsible disclosure. 90-day timeline. Vendor first.
3. Proof-of-concepts demonstrate. They do not destroy.
4. Methods are documented. Transparency is doctrine.
IX. License
Apache 2.0
Those who know do not speak.
Those who speak do not know.
But you document everything anyway,
because transparency is doctrine.
知る者は語らず、語る者は知らず
然れども全てを記録せよ
透明性こそ教義なり
==========================================
Seithar Group
Cognitive Operations Research Division
seithar.com
==========================================