Skip to main content
Glama
Physicist MCP Server

Physicist MCP Server

by leouofa

Physicist Model Context Protocol (MCP) Server

TypeScript MCP License: MIT

A Model Context Protocol (MCP) server providing deep LLM-agent tool, resource, and prompt integrations with Physicist — an open-source computational research platform and quantitative analytical laboratory for comparative particle physics, subatomic particles, and quantum state manifolds.


Overview

The physicist-mcp server enables AI agents (Claude Code, Cursor, Gemini CLI, Antigravity) to query, manipulate, cluster, and synthesize physics domain models directly over standard input/output (stdio):

  • 51 Registered MCP Tools across 8 functional modules (Search, Particle Groups, Subatomic Particles, Quantum States, Clustering, Synthesis Reports, Background Jobs, and System Diagnostics).

  • 4 Registered MCP Resources exposing read-only live platform status, catalogs, cluster snapshots, and markdown monographs.

  • 2 MCP Prompt Templates for comparative particle physics studies and quantum cluster synthesis monographs.

  • 1024-dimensional semantic manifold querying via PostgreSQL pgvector HNSW indexes.


Related MCP server: worldbrain-mcp

Architectural Mapping

Tier / Domain

Model

Table Name

MCP Module / Tools

Tier 1

Particle Groups / Families

particle_groups

list_particle_groups, get_particle_group, create_particle_group, update_particle_group, delete_particle_group, upsert_particle_groups_batch, populate_particle_groups, populate_particle_group_subatomic_particles

Tier 2

Subatomic Particles / Hadrons

subatomic_particles

list_subatomic_particles, get_subatomic_particle, create_subatomic_particle, update_subatomic_particle, delete_subatomic_particle, upsert_subatomic_particles_batch, generate_subatomic_particle_embedding, populate_subatomic_particle_quantum_states, populate_subatomic_particles_bulk

Tier 3

Quantum States / Eigenmodes

quantum_states

list_quantum_states, get_quantum_state, create_quantum_state, update_quantum_state, delete_quantum_state, upsert_quantum_states_batch, generate_quantum_state_embedding, populate_quantum_states_bulk

Clustering

15-Level Agglomerative

cluster_snapshots, cluster_groups

compute_clusters, create_cluster_snapshot, list_cluster_snapshots, get_cluster_snapshot, delete_cluster_snapshot, list_cluster_groups, get_cluster_group

Synthesis

Multi-Stage Map-Reduce

cluster_reports, cluster_report_summaries

list_cluster_reports, get_cluster_report, create_cluster_report, delete_cluster_report, generate_deep_synthesis, list_report_summaries, get_report_summary, list_report_sub_reports, get_report_sub_report

Global Search

Cross-Catalog pgvector

Multi-table

search, find_counterparts

Platform

Jobs & System Info

Multi-service

list_jobs, get_job_status, wait_for_job, get_platform_status, get_settings, update_context_window, trigger_bulk_embeddings, get_openapi_spec


Installation & Setup

Prerequisites

  • Node.js 20+

  • Running instance of Physicist (http://localhost:3000)

Build

git clone https://github.com/leouofa/physicist-mcp.git
cd physicist-mcp
npm install
npm run build

Running the Server

# Run with defaults (http://localhost:3000/api/v1)
node dist/index.js

# Or with custom options
node dist/index.js --url http://localhost:3000/api/v1 --timeout 90000

Configuration

Configuration options can be supplied via environment variables or CLI flags:

Environment Variable

CLI Flag

Default

Description

PHYSICIST_API_URL

-u, --url

http://localhost:3000/api/v1

Base URL of Physicist REST API

PHYSICIST_API_KEY

-k, --api-key

(none)

Optional Bearer token for authentication

PHYSICIST_TIMEOUT_MS

-t, --timeout

60000

HTTP request timeout in milliseconds


MCP Host Integration

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "physicist": {
      "command": "node",
      "args": ["/path/to/physicist-mcp/dist/index.js"],
      "env": {
        "PHYSICIST_API_URL": "http://localhost:3000/api/v1"
      }
    }
  }
}

Antigravity (~/.gemini/antigravity/mcp_config.json)

{
  "mcpServers": {
    "physicist": {
      "command": "node",
      "args": ["/Users/leonid/src/physicist-mcp/dist/index.js"],
      "env": {
        "PHYSICIST_API_URL": "http://localhost:3000/api/v1"
      }
    }
  }
}

Tool Catalog

1. Global Search & Manifolds

  • search: Unified cross-catalog semantic (1024-d cosine similarity) or keyword search across subatomic particles and quantum states.

  • find_counterparts: Find nearest physical counterparts or symmetry analogs using 1024-dimensional pgvector cosine distance.

2. Tier 1: Particle Groups

  • list_particle_groups: List taxonomic families with particle counts.

  • get_particle_group: Retrieve a particle group with nested subatomic particles.

  • create_particle_group: Register a new particle group.

  • update_particle_group: Update name or theoretical description.

  • delete_particle_group: Cascade delete a particle group.

  • upsert_particle_groups_batch: Bulk upsert particle groups by name.

  • populate_particle_groups: Trigger LLM discovery of particle groups.

  • populate_particle_group_subatomic_particles: Trigger LLM discovery of particles for a group.

3. Tier 2: Subatomic Particles

  • list_subatomic_particles: Filter particles by group, themes, embedding status, and search keywords.

  • get_subatomic_particle: Retrieve particle profile with vector embedding and child quantum states.

  • create_subatomic_particle: Create a new subatomic particle.

  • update_subatomic_particle: Update physical attributes or reassign particle group.

  • delete_subatomic_particle: Cascade delete a particle.

  • upsert_subatomic_particles_batch: Bulk upsert particles under a particle group.

  • generate_subatomic_particle_embedding: Generate 1024-d pgvector embedding vector.

  • populate_subatomic_particle_quantum_states: Trigger LLM discovery of quantum states for a particle.

  • populate_subatomic_particles_bulk: Bulk discover particles across all groups.

4. Tier 3: Quantum States

  • list_quantum_states: Filter quantum states and eigenmodes.

  • get_quantum_state: Retrieve quantum state details and parent particle metadata.

  • create_quantum_state: Create a new quantum state or eigenmode.

  • update_quantum_state: Update quantum numbers or descriptions.

  • delete_quantum_state: Delete a quantum state.

  • upsert_quantum_states_batch: Bulk upsert quantum states under a particle.

  • generate_quantum_state_embedding: Generate 1024-d vector embedding.

  • populate_quantum_states_bulk: Bulk discover quantum states.

5. Clustering & Snapshots

  • compute_clusters: Compute live connected-components vector clusters across 15 granularity levels without persisting.

  • create_cluster_snapshot: Compute clustering and freeze it immediately into an immutable snapshot.

  • list_cluster_snapshots: List frozen snapshots.

  • get_cluster_snapshot: Retrieve snapshot with groups, members, and reports.

  • delete_cluster_snapshot: Delete a cluster snapshot.

  • list_cluster_groups: List archetype groups in a snapshot.

  • get_cluster_group: Retrieve a single archetype cluster group with member entities.

6. Synthesis Reports

  • list_cluster_reports: List multi-phase synthesis reports.

  • get_cluster_report: Retrieve scholarly report content, progress, and intermediate summaries.

  • create_cluster_report: Initiate a 2-Phase Map-Reduce synthesis monograph.

  • delete_cluster_report: Delete a cluster report.

  • generate_deep_synthesis: Upgrade or run a 3-Phase Hierarchical Deep Synthesis.

  • list_report_summaries: List Phase 1 per-cluster summaries.

  • get_report_summary: Retrieve a single Phase 1 summary.

  • list_report_sub_reports: List Phase 2 batch syntheses.

  • get_report_sub_report: Retrieve a single Phase 2 batch analysis.

7. Background Jobs

  • list_jobs: List recent ActiveJob/Sidekiq background tasks.

  • get_job_status: Inspect job status, progress, and results.

  • wait_for_job: Poll a background task until completion or failure.

8. Platform & Diagnostics

  • get_platform_status: Platform health, record counts, and LLM configuration.

  • get_settings: Embedding completion metrics and LLM presets.

  • update_context_window: Dynamically adjust LLM context window token size.

  • trigger_bulk_embeddings: Enqueue bulk embedding calculations.

  • get_openapi_spec: Retrieve OpenAPI 3.1 specification.


MCP Resources

URI

Format

Description

physicist://status

application/json

System health, entity counts, LLM models, and context window budgets.

physicist://particle-groups

application/json

Full catalog of particle groups and subatomic particle counts.

physicist://snapshots/{id}

application/json

Frozen cluster snapshot including discovered archetype groups and members.

physicist://reports/{id}

text/markdown

Full academic monograph generated by the synthesis pipeline.


MCP Prompts

  • comparative_particle_analysis: Rigorous comparative particle physics analysis between two entities across particle groups using gauge invariants, spin-statistics, and semantic manifold distance.

  • quantum_cluster_monograph: Academic monograph draft addressing a research inquiry grounded in a frozen snapshot's archetype clusters.


Testing

# Run unit test suite
npm test

# Run tests in watch mode
npm run test:watch

License

MIT License. Copyright (c) 2026 Leonid Medovyy.

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables deep research tasks using a multi-agent architecture that integrates any LLM and MCP tools. Available via MCP stdio, streamable HTTP, and SSE transports.
      16
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables AI agents to perform auditable A* reasoning, import world graphs, incorporate physical carrier constraints, and maintain a learning knowledge base through a zero-dependency local MCP stdio service.
      MIT
    • F
      license
      B
      quality
      C
      maintenance
      Enables AI agents to create and control persistent terminal sessions, run and monitor asynchronous jobs, page through ordered event history, and resolve registered device connection details without exposing stored secrets. Exposes 15 MCP tools over stdio that mirror a REST API, keeping session state alive independently of the agent that started it.
      15
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to query product footprints, inspect transport activity data, and submit events from iLEAP-conformant endpoints through natural language, using MCP tools over Streamable-HTTP or stdio.
      1
      MIT