Mojo MCP

FastMCP (Python) → Python extension bindings → native Mojo 1.0 CPU kernels.

Run

Requires Linux/macOS supported by Mojo and Python 3.12 or 3.13. uv installs Mojo 1.0.0 along with the Python dependencies; no separate compiler setup is needed.

uv sync
uv run mojo-mcp

The default transport is stdio: an MCP client launches this process and exchanges JSON-RPC on stdin/stdout. It is not an interactive shell. Logs go to stderr. The first startup compiles _kernels.mojo into a cached shared library through mojo.importer. Subsequent startups reuse it; source changes trigger recompilation. Allow extra time for first startup, or prewarm with:

uv run python -c 'from mojo_mcp.server import mcp'

The package directory must be writable for __mojocache__. This project ships Mojo source rather than a platform-specific precompiled binary.

Related MCP server: mcp_calculator

MCP client configuration

Replace the project path and use an absolute uv executable path if your client cannot find it on PATH:

{
  "mcpServers": {
    "mojo-kernels": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/mojo-mcp", "mojo-mcp"]
    }
  }
}

Pi feedback loop

This checkout is registered as mojo-kernels in ~/.pi/agent/mcp.json with directTools: true, using an absolute uv path and this project's directory.

1. Run /reload in Pi after changing its MCP configuration.

2. Run /mcp reconnect mojo-kernels to populate/refresh tool metadata. If direct tools are not visible yet, run /reload again after the connection succeeds.

3. Ask the agent to call kernel_info, dot_product, or axpy on mojo-kernels.

4. After editing Python or Mojo code, run /mcp reconnect mojo-kernels to restart the process; the Mojo importer recompiles changed source automatically. If tool names or schemas changed, follow with /reload.

The adapter's proxy also supports discovery via mcp({server: "mojo-kernels"}).

Tools

• dot_product(x, y) → { "value": 32.0 } for [1,2,3] and [4,5,6].

• axpy(alpha, x, y) → { "values": [6.0,9.0,12.0] } for alpha 2 and those vectors.

• kernel_info() → backend, precision, and input limit.

Vectors must have equal lengths, contain finite numbers, and have at most 10,000 elements. Empty inputs return zero/an empty vector. Non-finite outputs (including floating-point overflow) are reported as tool errors, not invalid JSON values.

Streaming telemetry server

uv run mojo-telemetry

Open http://127.0.0.1:8766 and click Start demo. FastAPI accepts batches; a persistent Mojo ring buffer maintains rolling statistics and detects spikes; WebSockets stream summaries to a live chart. The MCP server is unchanged.

See docs/telemetry.md for the ingestion API, architecture, limits, and lifecycle commands. Local, single-process, in-memory prototype.

Network behavior simulator

uv run mojo-network

Open http://127.0.0.1:8767 to experiment with bandwidth, latency, packet loss, queue capacity, timeouts, and retry backoff. Compare retries against a no-retry baseline and export the results. Mojo runs the discrete-event model; Python serves the dashboard. No real network traffic is generated by the simulation.

See docs/network.md for model assumptions, API, and limits.

Explore Mojo without MCP

playground/ contains three creative standalone programs: a ray-traced alien planet, a retro music synthesizer, and a procedural cave world. The seven introductory examples live in playground/fundamentals/. No server changes or additional packages needed.

Development

uv run pytest
uv run ruff check .
uv run ruff format --check .

tests/ exercises actual compiled kernels, MCP calls, validation, and a real stdio subprocess. No mock or Python fallback implements the arithmetic.

Add your own kernel

1. Add native computation to src/mojo_mcp/_kernels.mojo. Keep Python object conversion at the binding boundary, outside hot loops.

2. Wrap it in a function taking/returning PythonObject and register it with module.def_function[...] in PyInit__kernels.

3. Add a typed @mcp.tool function in src/mojo_mcp/server.py with input limits and JSON-safe output validation. Call the extension with positional arguments.

4. Add native and MCP tests, then restart the server to compile your changes.

Scope and performance

Mojo 1.0 supports this architecture, but its Python extension bindings are still marked beta upstream. This starter uses the official importer and bindings, not ctypes, subprocess-per-call, arbitrary code execution, or a CLI JSON bridge.

These are simple Float64 CPU kernels, not GPU kernels. They copy Python lists into native Mojo lists and copy results back. MCP JSON serialization, conversion, and Python's GIL can dominate small operations; this is not a claim of speedup over NumPy. Benchmark your real workload before adding SIMD, GPU execution, or buffer-based zero-copy input. The server is local stdio only; remote deployment would need authentication, transport/resource limits, and operational hardening.

References: Mojo Python bindings, FastMCP.