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:5001

Using 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 graph

MiroFish'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.js

The server uses stdio transport — Claude Code launches it as a subprocess and communicates over stdin/stdout.

---

License

MIT

mirofish-mcp-server