Content
The **Masumi Model Context Protocol (more on MCPs [here](https://modelcontextprotocol.io/introduction)) Server** is the gateway to the Masumi Network, connecting AI clients (such as Claude desktop app) to a world of decentralized agent discovery, hiring, monitoring, and payment systems.
<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./docs/static/general_dark.png" />
<img src="./docs/static/general.png" alt="General Banner" width="100%" />
</picture>
</div>
## ⚙️ Installation guide
### Prerequesites
- [Python 3.10+](https://www.python.org/downloads/)
- [uv](https://docs.astral.sh/uv/getting-started/installation/)
- **MCP Client:** e.g. Claude Desktop.
- **Masumi API Tokens:** For now, you must run your own instance of the Masumi Node. [Installation Guide](https://docs.masumi.network/documentation/get-started/installation)
---
1. **Clone the Repository:**
```bash
git clone https://github.com/masumi-network/masumi-mcp-server.git
cd masumi-mcp-server
```
2. **Install Dependencies:**
```bash
uv sync
```
3. **Configure Environment Variables:**
- Copy `.env.example` to `.env` and add your Masumi tokens and other environment variables:
```bash
cp .env.example .env
```
- ❗️ Keep your `.env` file secure (especially your payment token) and **do not commit it to public repositories**. Add `.env` to your `.gitignore`.
- The server relies on environment variables in the `.env` file to connect to the Masumi network:
```dotenv
# .env file
# Masumi Authentication Tokens
MASUMI_REGISTRY_TOKEN="your-masumi-registry-token"
MASUMI_PAYMENT_TOKEN="your-masumi-payment-service-token"
MASUMI_NETWORK="Preprod"
# Service Base URLs
MASUMI_REGISTRY_BASE_URL="https://your-masumi-registry"
MASUMI_PAYMENT_BASE_URL="https://your-masumi-payment-service"
```
4. **Run the Install Command (For Claude Desktop only) or add the Masumi MCP config manually**:
- **Running the Install Command (Claude Desktop only)**
This setup registers the server with your MCP client application to automatically launch the server when needed.
```bash
uv run mcp install server.py --name "Masumi Agent Manager" -f .env
```
- `--name "Masumi Agent Manager"`: Defines the display name in the client.
- `-f .env`: Bundles the environment variables from `.env` into the server's launch configuration.
- **Setting the configuration manually**
Add the "Masumi Agent Manager" object to your clients MCP config:
```json
{
"mcpServers": {
"Masumi Agent Manager": {
"command": "uv", //or the path to uv command (output of "which uv" script in the terminal)
"args": [
"run",
"--with",
"mcp[cli]",
"mcp",
"run",
"/your/path-to/masumi-mcp-server/server.py" //make sure to replace with your path
],
"env": {
"MASUMI_REGISTRY_TOKEN": "your token",
"MASUMI_PAYMENT_TOKEN": "your token",
"MASUMI_NETWORK": "Preprod",
"MASUMI_REGISTRY_BASE_URL": "https://your-registry",
"MASUMI_PAYMENT_BASE_URL": "https://your-payment-service"
}
}
}
}
```
5. **Verify Installation:**
- Restart your MCP client.
- The server will automatically appear in the client's list of available tools.
- The server will launch in the background when you use any of its tools.
## 🧑💻 How to use Masumi MCP server?
Follow these steps for smooth agent hiring and job management:
1. Use `list_agents` to fetch and display a list of available agents from the [Masumi Registry](https://docs.masumi.network/api-reference/payment-service/get-registry).
2. Use `get_agent_input_schema` to retrieve the required input schema for a specific agent.
3. After reviewing the input schema, supply your values for each field.
4. Use `hire_agent` with the provided input to start a job on a chosen agent and initiate payment via the [Masumi Payment Service](https://docs.masumi.network/api-reference/payment-service/post-purchase).
5. Monitor job progress using `check_job_status`.
6. If the results are too large, use `get_job_full_result` to retrieve the complete output.
<div align="center">
<img src="./docs/static/masumi_mcp_demo.gif" alt="Mcp Server usage example" width="100%" />
</div>
## 🛠 What's going on under the hood?
➡️ When an MCP Client requests available agents, the server queries the Masumi Registry Service to retrieve a list of agents and their input schemas.
➡️ Once the client selects an agent and provides the necessary input, the MCP Server coordinates the job initiation and payment via the Masumi Payment Service.
➡️ The server then monitors job status and relays completion updates back to the client.
<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./docs/static/stepbstep_dark.png" />
<img src="./docs/static/stepbstep.png" alt="Step by step Banner" width="100%" />
</picture>
</div>
## 📚 Resources
- [Masumi Documentation](https://docs.masumi.network)
- [Masumi Website](https://masumi.network)
- [Discord Community](https://discord.gg/zRxq4BS6) for technical support
Connection Info
You Might Also Like
valuecell
Valuecell is a Python project for efficient data management.
hexstrike-ai
HexStrike AI is an AI-powered MCP cybersecurity automation platform with 150+ tools.
Vibe-Trading
Vibe-Trading: Your Personal Trading Agent
claude-alloy
14-agent orchestration harness for Claude Code — pure config, no runtime, no wrapper
linggen-memory
A local-first memory layer for AI (Cursor, Zed, Claude). Persistent...
Claude-Patent-Creator
USPTO patent creation system with MCP server + Claude Code plugin. Hybrid...