mirofish-mcp-server
MCP (Model Context Protocol) server for MiroFish — the AI-powered multi-agent prediction engine. Connect Claude Code (or any MCP-compatible AI client) directly to your local MiroFish instance.
---
What this does
MiroFish lets you upload documents, build a knowledge graph, spin up thousands of autonomous AI agents, and simulate future scenarios. This MCP server exposes all of that as tools Claude can call directly from a conversation.
┌─────────────┐ stdio ┌───────────────────┐ HTTP ┌──────────────────┐
│ Claude Code │ ◄────────────► │ mirofish-mcp- │ ────────────► │ MiroFish Backend │
│ │ │ server (Node.js) │ │ (Flask on :5001) │
└─────────────┘ └───────────────────┘ └──────────────────┘---
Prerequisites
- Node.js 18+
- MiroFish running locally — clone and start it first:
git clone https://github.com/666ghj/MiroFish.git
cd MiroFish
cp .env.example .env
npm run setup:all
npm run dev # starts backend at http://localhost:5001Using Claude as MiroFish's LLM — MiroFish accepts any OpenAI-compatible API. To use Claude, set these in your MiroFish .env:
LLM_API_KEY=sk-ant-api03-... # your Anthropic API key
LLM_BASE_URL=https://api.anthropic.com/v1
LLM_MODEL_NAME=claude-sonnet-4-6
ZEP_API_KEY=... # still required for the knowledge graphMiroFish's LLM client passes base_url directly to the OpenAI SDK, so Claude handles all internal AI work — ontology extraction, agent profiling, simulation decisions, report generation — with no code changes.
---
Installation
git clone https://github.com/thisisaman408/mirofish-mcp-server.git
cd mirofish-mcp-server
npm install
npm run build---
Connect to Claude Code
Create a .mcp.json file in the directory where you run Claude Code (or your project root):
{
"mcpServers": {
"mirofish": {
"command": "node",
"args": ["/absolute/path/to/mirofish-mcp-server/dist/index.js"],
"env": {
"MIROFISH_BASE_URL": "http://localhost:5001"
}
}
}
}Replace /absolute/path/to/ with the actual path where you cloned this repo. Then restart Claude Code — the MiroFish tools will appear automatically.
Custom backend URL
If MiroFish runs on a different host or port, change MIROFISH_BASE_URL:
"env": {
"MIROFISH_BASE_URL": "http://192.168.1.10:5001"
}---
Available Tools (40 total)
Health
| Tool | Description | |------|-------------| | mirofish_health_check | Check if the MiroFish backend is running |
Projects
| Tool | Description | |------|-------------| | mirofish_list_projects | List all projects | | mirofish_get_project | Get project details by ID | | mirofish_delete_project | Delete a project | | mirofish_reset_project | Reset project state to rebuild graph |
Knowledge Graph
| Tool | Description | |------|-------------| | mirofish_generate_ontology | Upload documents and generate entity/edge ontology | | mirofish_build_graph | Build a Zep knowledge graph from a project (async) | | mirofish_get_graph_data | Get all nodes and edges from a graph | | mirofish_delete_graph | Delete a graph |
Tasks
| Tool | Description | |------|-------------| | mirofish_get_task | Poll an async task's progress | | mirofish_list_tasks | List all background tasks |
Simulation
| Tool | Description | |------|-------------| | mirofish_create_simulation | Create a new simulation from a project | | mirofish_prepare_simulation | Generate agent profiles + config (async) | | mirofish_prepare_status | Check preparation progress | | mirofish_start_simulation | Start running the simulation | | mirofish_stop_simulation | Stop a running simulation | | mirofish_get_simulation | Get simulation details and status | | mirofish_list_simulations | List all simulations | | mirofish_simulation_run_status | Get real-time run status | | mirofish_simulation_run_status_detail | Get detailed round/agent progress | | mirofish_get_simulation_profiles | Get generated agent profiles | | mirofish_get_simulation_config | Get simulation config | | mirofish_simulation_history | Get history of all simulations |
Simulation Results
| Tool | Description | |------|-------------| | mirofish_get_entities | Get all entities from the knowledge graph | | mirofish_get_entity_detail | Get a specific entity's context | | mirofish_get_entities_by_type | Get entities filtered by type | | mirofish_get_simulation_actions | Get all agent actions during the run | | mirofish_get_simulation_timeline | Get chronological event timeline | | mirofish_get_agent_stats | Get agent behavior statistics | | mirofish_get_simulation_posts | Get posts generated by agents | | mirofish_get_simulation_comments | Get comments/replies generated by agents |
Interview
| Tool | Description | |------|-------------| | mirofish_interview_agent | Chat with a specific simulated agent | | mirofish_interview_batch | Ask multiple agents the same question | | mirofish_interview_all | Ask all agents a question | | mirofish_interview_history | Get conversation history with an agent |
Reports
| Tool | Description | |------|-------------| | mirofish_generate_report | Generate prediction report (async) | | mirofish_report_generate_status | Check report generation progress | | mirofish_get_report | Get full report content | | mirofish_get_report_by_simulation | Get report by simulation ID | | mirofish_list_reports | List all reports | | mirofish_delete_report | Delete a report | | mirofish_get_report_progress | Real-time section-by-section progress | | mirofish_get_report_sections | Get all completed sections | | mirofish_get_report_section | Get a single section by index | | mirofish_check_report_status | Check if a simulation has a report | | mirofish_chat_with_report_agent | Chat with the AI Report Agent about results |
Debug Tools
| Tool | Description | |------|-------------| | mirofish_search_graph | Semantic search over the knowledge graph | | mirofish_graph_statistics | Get node/edge counts and entity distribution | | mirofish_env_status | Check simulation environment status | | mirofish_close_env | Shut down a simulation environment |
---
Example conversation with Claude
Once connected, you can talk to Claude naturally:
"List my MiroFish projects"
"Create a simulation about public opinion on climate policy using project proj_abc123"
"Interview agent Li Wei — ask her what she thinks about the new carbon tax"
"Generate a prediction report for simulation sim_xyz789 and show me the executive summary"
"Search the knowledge graph for anything about social media sentiment"
---
Workflow
The typical end-to-end flow in MiroFish:
1. Generate ontology → mirofish_generate_ontology (upload docs)
2. Build graph → mirofish_build_graph (async, poll with get_task)
3. Create simulation → mirofish_create_simulation
4. Prepare simulation → mirofish_prepare_simulation (async, generates agent profiles)
5. Start simulation → mirofish_start_simulation
6. Monitor / results → get_posts, get_actions, get_timeline
7. Generate report → mirofish_generate_report (async)
8. Interview agents → mirofish_interview_agent
9. Chat about results → mirofish_chat_with_report_agent---
Development
# Edit src/index.ts, then rebuild
npm run build
# Run directly (requires MiroFish backend)
node dist/index.jsThe server uses stdio transport — Claude Code launches it as a subprocess and communicates over stdin/stdout.
---
License
MIT
