Hyperledger Fabric MCP Server
A Model Context Protocol (MCP) server that enables AI assistants to interact with Hyperledger Fabric blockchain networks.
Features
- Query Chaincode - Execute read-only queries on smart contracts
- Invoke Chaincode - Submit transactions to the blockchain
- Get Block Info - Retrieve detailed information about specific blocks
- Get Blockchain Info - Get network statistics (block height, hashes)
- Get Transaction History - View history for specific assets
- List Enrolled Identities - View wallet identities
- Chaincode Lifecycle Management - Query installed, approved, and committed chaincodes
- Commit Readiness Check - Verify chaincode definitions before committing
- Channel Management - List channels and get channel information
- Multiple Transport Modes - Supports both stdio and HTTP/SSE (for web clients)
Prerequisites
- Node.js v18+
- A running Hyperledger Fabric network
- Valid connection profile JSON
- Enrolled user identity (certificate + private key)
Installation
npm install
Configuration
Option 1: Environment Variables
Copy the template and configure:
cp env.template .env
Edit .env with your settings:
# Fabric Network Configuration
FABRIC_CHANNEL=mychannel
FABRIC_CHAINCODE=basic
FABRIC_MSP_ID=Org1MSP
FABRIC_WALLET_PATH=./wallet
FABRIC_CONNECTION_PROFILE=./connection-profile.json
FABRIC_USER_ID=appUser
# Transport Configuration (optional)
MCP_TRANSPORT=stdio # "stdio" or "http"
MCP_PORT=3000 # HTTP port (only used when MCP_TRANSPORT=http)
Option 2: Claude Desktop Config
Add environment variables directly in claude_desktop_config.json:
{
"mcpServers": {
"hyperledger-fabric": {
"command": "npx",
"args": ["-y", "@adityajoshi12/fabric-mcp-server"],
"env": {
"FABRIC_CHANNEL": "mychannel",
"FABRIC_CHAINCODE": "basic",
"FABRIC_MSP_ID": "Org1MSP",
"FABRIC_WALLET_PATH": "/path/to/wallet",
"FABRIC_CONNECTION_PROFILE": "/path/to/connection-profile.json",
"FABRIC_USER_ID": "appUser"
}
}
}
}
Wallet Setup
Create a wallet from your certificate and private key:
npm run create-wallet -- ./path/to/private.key ./path/to/cert.pem Org1MSP appUser
Or set environment variables and run:
export PRIVATE_KEY_PATH=./path/to/private.key
export CERTIFICATE_PATH=./path/to/cert.pem
npm run create-wallet
Build & Run
Stdio Mode (Default)
# Build TypeScript
npm run build
# Run the server
npm start
# Or build and run together
npm run dev
HTTP Mode (for Web Clients)
Run the MCP server as an HTTP server with SSE support:
MCP_TRANSPORT=http MCP_PORT=8080 npm start
Available Tools
1. invoke_chaincode
Submit a transaction to the blockchain.
Parameters:
function(string): Chaincode function nameargs(array): Arguments to pass
Example:
CreateAsset with args: ["asset1", "blue", "20", "john", "500"]
2. query_chaincode
Query the blockchain (read-only).
Parameters:
function(string): Chaincode function nameargs(array): Arguments to pass
Example:
GetAllAssets with args: []
ReadAsset with args: ["asset1"]
3. get_block_info
Get information about a specific block.
Parameters:
blockNumber(number): The block number to retrieve
4. get_blockchain_info
Get blockchain statistics including total blocks and hashes.
Parameters: None
5. get_transaction_history
Get transaction history for an asset (requires chaincode support).
Parameters:
assetId(string): The asset ID
6. list_enrolled_identities
List all identities in the wallet.
Parameters: None
7. get_installed_chaincodes
Get list of chaincodes installed on the peer.
Parameters: None
8. get_approved_chaincode
Get the approved chaincode definition for an organization.
Parameters:
chaincodeName(string): The name of the chaincode
9. get_committed_chaincode
Get the committed chaincode definition on the channel.
Parameters:
chaincodeName(string): The name of the chaincode
10. check_commit_readiness
Check if a chaincode definition is ready to be committed.
Parameters:
chaincodeName(string): The name of the chaincodesequence(number): The sequence number of the chaincode definitionversion(string): The version of the chaincode
11. list_channels
List all channels the peer has joined.
Parameters: None
12. get_channel_info
Get information about a specific channel.
Parameters:
channelName(string): The name of the channel
Example Usage with AI Assistant
"How many blocks are in the network?"
→ Uses get_blockchain_info
"List all assets"
→ Uses query_chaincode with GetAllAssets
"Create an asset with ID 1001, color red, size 20, owner john, value 500"
→ Uses invoke_chaincode with CreateAsset
"Show me block 10"
→ Uses get_block_info with blockNumber 10
"What chaincodes are installed?"
→ Uses get_installed_chaincodes
"Is the 'basic' chaincode committed?"
→ Uses get_committed_chaincode with chaincodeName "basic"
"List all channels"
→ Uses list_channels
"Check commit readiness for chaincode 'mycc' version 1.0"
→ Uses check_commit_readiness
Project Structure
fabric-mcp-server/
├── app.ts # Main MCP server
├── create-wallet.ts # Wallet creation utility
├── dist/ # Compiled JavaScript
├── wallet/ # Identity wallet
├── env.template # Environment template
├── tsconfig.json # TypeScript config
└── package.json # Dependencies
Troubleshooting
"Identity not found in wallet"
Run npm run create-wallet with your credentials.
"Cannot find module" error
Ensure you've run npm run build and the path in config is absolute.
Connection errors
Verify your connection profile paths and that the Fabric network is running.
Usage
Using npx (without installing)
{
"mcpServers": {
"hyperledger-fabric": {
"command": "npx",
"args": ["-y", "fabric-mcp-server"],
"env": {
"FABRIC_CHANNEL": "mychannel",
"FABRIC_CHAINCODE": "basic",
"FABRIC_MSP_ID": "Org1MSP",
"FABRIC_WALLET_PATH": "/path/to/wallet",
"FABRIC_CONNECTION_PROFILE": "/path/to/connection-profile.json",
"FABRIC_USER_ID": "appUser"
}
}
}
}
Installing locally
npm install -g fabric-mcp-server
{
"mcpServers": {
"hyperledger-fabric": {
"command": "fabric-mcp-server",
"env": {
"FABRIC_CHANNEL": "mychannel",
"FABRIC_CHAINCODE": "basic",
"FABRIC_MSP_ID": "Org1MSP",
"FABRIC_WALLET_PATH": "/path/to/wallet",
"FABRIC_CONNECTION_PROFILE": "/path/to/connection-profile.json",
"FABRIC_USER_ID": "appUser"
}
}
}
}
Using SSE
{
"mcpServers": {
"hyperledger-fabric": {
"url": "http://localhost:3000/mcp",
}
}
}
License
ISC