# 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
```bash
npm install
```
## Configuration
### Option 1: Environment Variables
Copy the template and configure:
```bash
cp env.template .env
```
Edit `.env` with your settings:
```env
# 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`:
```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:
```bash
npm run create-wallet -- ./path/to/private.key ./path/to/cert.pem Org1MSP appUser
```
Or set environment variables and run:
```bash
export PRIVATE_KEY_PATH=./path/to/private.key
export CERTIFICATE_PATH=./path/to/cert.pem
npm run create-wallet
```
## Build & Run
### Stdio Mode (Default)
```bash
# 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:
```bash
MCP_TRANSPORT=http MCP_PORT=8080 npm start
```
## Available Tools
### 1. `invoke_chaincode`
Submit a transaction to the blockchain.
**Parameters:**
- `function` (string): Chaincode function name
- `args` (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 name
- `args` (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 chaincode
- `sequence` (number): The sequence number of the chaincode definition
- `version` (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)
```json
{
"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
```bash
npm install -g fabric-mcp-server
```
```json
{
"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
```json
{
"mcpServers": {
"hyperledger-fabric": {
"url": "http://localhost:3000/mcp",
}
}
}
```
## License
ISC
