Skip to main content
Glama

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) │
└─────────────┘                └───────────────────┘               └──────────────────┘

Related MCP server: Docalyze

Prerequisites

  1. Node.js 18+

  2. 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

Available Tools

50 tools
mirofish_build_graphBuild Knowledge GraphA

Build a knowledge graph from a project's documents and ontology using Zep. This is an async operation — returns a task_id to poll with mirofish_get_task.

Inputs: project_id (required), force, chunk_size, graph_name, +1 more.

mirofish_chat_with_report_agentChat with Report AgentA
Read-only

Have a conversation with the Report Agent about a simulation's results. The agent can search the knowledge graph and use tools to answer your questions.

Inputs: message (required), simulation_id (required), chat_history.

mirofish_check_report_statusCheck Report StatusA
Read-onlyIdempotent

Check if a simulation has a report and its status. Used to determine if interview is unlocked.

Inputs: simulation_id (required).

mirofish_close_envClose EnvironmentC
Idempotent

Close/shut down a simulation environment.

Inputs: simulation_id (required).

mirofish_create_simulationCreate SimulationA

Create a new multi-agent simulation from a project. Requires a completed knowledge graph.

Inputs: project_id (required), graph_id, enable_reddit, enable_twitter.

mirofish_delete_graphDelete GraphB
Destructive

Delete a Zep knowledge graph by its ID.

Inputs: graph_id (required).

mirofish_delete_projectDelete ProjectA
Destructive

Delete a MiroFish project and all its associated data.

Inputs: project_id (required).

mirofish_delete_reportDelete ReportB
Destructive

Delete a generated report.

Inputs: report_id (required).

mirofish_env_statusGet Environment StatusA
Read-onlyIdempotent

Check the status of the simulation environment (OASIS engine).

Inputs: simulation_id (required).

mirofish_generate_ontologyGenerate OntologyA

Upload seed documents and a simulation requirement to generate an ontology (entity types and edge types). This creates a new project. Accepts PDF/MD/TXT file URLs or paths. NOTE: This endpoint expects multipart/form-data with actual file uploads — use the simulation_requirement and project_name to describe the scenario, and provide document text directly.

Inputs: simulation_requirement (required), project_name, document_text, additional_context.

mirofish_generate_reportGenerate ReportA

Generate a prediction/analysis report from a completed simulation. Async — returns task_id to poll.

Inputs: simulation_id (required), force_regenerate.

mirofish_get_agent_statsGet Agent StatisticsB
Read-onlyIdempotent

Get statistics about agent behavior during a simulation.

Inputs: simulation_id (required).

mirofish_get_entitiesGet Graph EntitiesA
Read-onlyIdempotent

Get all filtered entities from a knowledge graph. Only returns nodes matching predefined entity types.

Inputs: graph_id (required), enrich, entity_types.

mirofish_get_entities_by_typeGet Entities by TypeA
Read-onlyIdempotent

Get all entities of a specific type from a knowledge graph.

Inputs: graph_id (required), entity_type (required), enrich.

mirofish_get_entity_detailGet Entity DetailA
Read-onlyIdempotent

Get detailed information about a specific entity including its context and relationships.

Inputs: graph_id (required), entity_uuid (required).

mirofish_get_graph_dataGet Graph DataA
Read-onlyIdempotent

Retrieve the full knowledge graph data (nodes and edges) for a given graph ID.

Inputs: graph_id (required).

mirofish_get_projectGet ProjectA
Read-onlyIdempotent

Get details of a specific MiroFish project by its ID, including ontology, files, status, and graph info.

Inputs: project_id (required).

mirofish_get_reportGet ReportA
Read-onlyIdempotent

Get a completed report by its ID — includes outline, markdown content, and metadata.

Inputs: report_id (required).

mirofish_get_report_by_simulationGet Report by SimulationB
Read-onlyIdempotent

Get the report associated with a specific simulation.

Inputs: simulation_id (required).

mirofish_get_report_progressGet Report ProgressB
Read-onlyIdempotent

Get real-time progress of report generation including current section being written.

Inputs: report_id (required).

mirofish_get_report_sectionGet Single Report SectionA
Read-onlyIdempotent

Get the content of a specific section by index.

Inputs: report_id (required), section_index (required).

mirofish_get_report_sectionsGet Report SectionsA
Read-onlyIdempotent

Get all generated sections of a report. Can be polled during generation to get sections as they complete.

Inputs: report_id (required).

mirofish_get_simulationGet SimulationC
Read-onlyIdempotent

Get details and current status of a specific simulation.

Inputs: simulation_id (required).

mirofish_get_simulation_actionsGet Simulation ActionsA
Read-onlyIdempotent

Get the action log of a simulation — all agent actions taken during the run.

Inputs: simulation_id (required).

mirofish_get_simulation_commentsGet Simulation CommentsA
Read-onlyIdempotent

Get comments/replies generated by agents during the simulation.

Inputs: simulation_id (required).

mirofish_get_simulation_configGet Simulation ConfigC
Read-onlyIdempotent

Get the simulation configuration parameters.

Inputs: simulation_id (required).

mirofish_get_simulation_postsGet Simulation PostsA
Read-onlyIdempotent

Get social media posts generated by agents during the simulation (Twitter/Reddit style).

Inputs: simulation_id (required).

mirofish_get_simulation_profilesGet Simulation ProfilesB
Read-onlyIdempotent

Get the agent profiles generated for a simulation.

Inputs: simulation_id (required).

mirofish_get_simulation_timelineGet Simulation TimelineA
Read-onlyIdempotent

Get a chronological timeline of events during the simulation.

Inputs: simulation_id (required).

mirofish_get_taskGet Task StatusB
Read-onlyIdempotent

Check the status and progress of an async task (graph building, simulation preparation, report generation, etc.).

Inputs: task_id (required).

mirofish_graph_statisticsGet Graph StatisticsA
Read-onlyIdempotent

Get statistics about a knowledge graph — node counts, edge counts, entity type distribution.

Inputs: graph_id (required).

mirofish_health_checkHealth CheckA
Read-onlyIdempotent

Check if the MiroFish backend is running and healthy. Returns service status.

Inputs: no named parameters.

mirofish_interview_agentInterview AgentA
Read-only

Interview (chat with) a specific simulated agent. The agent responds based on its personality, memories, and actions during the simulation.

Inputs: message (required), agent_name (required), simulation_id (required).

mirofish_interview_allInterview All AgentsA
Read-only

Send the same question to ALL agents in the simulation. Returns all their responses.

Inputs: message (required), simulation_id (required).

mirofish_interview_batchBatch Interview AgentsA
Read-only

Send the same question to multiple agents at once. Useful for gathering diverse perspectives.

Inputs: message (required), agent_names (required), simulation_id (required).

mirofish_interview_historyGet Interview HistoryC
Read-onlyIdempotent

Get the conversation history for a specific agent interview.

Inputs: agent_name (required), simulation_id (required).

mirofish_list_projectsList ProjectsA
Read-onlyIdempotent

List all MiroFish projects. Each project contains seed documents and ontology definitions for simulation.

Inputs: limit.

mirofish_list_reportsList ReportsA
Read-onlyIdempotent

List all generated reports, optionally filtered by simulation.

Inputs: limit, simulation_id.

mirofish_list_simulationsList SimulationsA
Read-onlyIdempotent

List all simulations, optionally filtered by project.

Inputs: limit, project_id.

mirofish_list_tasksList TasksA
Read-onlyIdempotent

List all background tasks and their statuses.

Inputs: no named parameters.

mirofish_prepare_simulationPrepare SimulationA

Prepare a simulation environment — reads entities from the graph, generates agent profiles via LLM, and creates simulation config. Async — returns task_id.

Inputs: simulation_id (required), entity_types, force_regenerate, use_llm_for_profiles, +1 more.

mirofish_prepare_statusGet Preparation StatusC
Read-onlyIdempotent

Check the progress of simulation preparation.

Inputs: task_id, simulation_id.

mirofish_report_generate_statusGet Report Generation StatusC
Read-onlyIdempotent

Check the progress of report generation.

Inputs: task_id, simulation_id.

mirofish_reset_projectReset ProjectA
Idempotent

Reset a project's state so its knowledge graph can be rebuilt. Keeps the ontology but clears the graph.

Inputs: project_id (required).

mirofish_search_graphSearch Knowledge GraphB
Read-onlyIdempotent

Search the knowledge graph for facts and information. Uses Zep's semantic search.

Inputs: query (required), graph_id (required), limit.

mirofish_simulation_historyGet Simulation HistoryB
Read-onlyIdempotent

Get the history of all simulations with their run status and results.

Inputs: limit.

mirofish_simulation_run_statusGet Simulation Run StatusB
Read-onlyIdempotent

Get the real-time running status of a simulation including process state.

Inputs: simulation_id (required).

mirofish_simulation_run_status_detailGet Detailed Run StatusA
Read-onlyIdempotent

Get detailed running status of a simulation including round progress and agent activity.

Inputs: simulation_id (required).

mirofish_start_simulationStart SimulationA

Start running a prepared simulation. Agents will begin interacting in the simulated environment.

Inputs: simulation_id (required).

mirofish_stop_simulationStop SimulationA
Idempotent

Stop a running simulation.

Inputs: simulation_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 50 tools

    Disambiguation2/5

    Several tools have overlapping purposes, especially around status/progress monitoring: get_task, prepare_status, report_generate_status, get_report_progress, simulation_run_status, and check_report_status all serve similar roles with subtle differences. This makes it difficult for an agent to know which tool to call, leading to potential misselection.

    Naming Consistency3/5

    All tools share the 'mirofish_' prefix, which is good for namespacing, but the pattern after the prefix is inconsistent. Some tools use verb_noun (get_simulation, list_projects), others use noun_verb (report_generate_status), and a few are noun_noun phrases (simulation_run_status, simulation_history). This mixed style reduces predictability.

    Tool Count2/5

    With 50 tools, the server is far above the typical well-scoped range. Many tools are redundant (e.g., multiple report progress/status tools, several simulation status variants), making the surface area heavy and harder to navigate. The count should be reduced by consolidating related operations.

    Completeness4/5

    The tool set covers the main workflow comprehensively: project creation, ontology generation, graph building, simulation lifecycle, agent interviews, and report generation. Minor gaps exist, such as no update_project, no update_simulation_config, and no pause/resume for simulations, but these are not critical given the breadth of coverage.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers