modelcontextprotocol
Six Model Context Protocol (MCP) servers in a single Rust binary,
implementing the MCP 2026-07-28 specification
over stdio:
| Server | Identity | What it does |
|---|---|---|
filesystem |
mcp-filesystem |
Secure read/write access restricted to allowed directories |
fetch |
mcp-fetch |
Fetch URLs and convert HTML to markdown, with optional robots.txt enforcement |
memory |
mcp-memory |
Persistent knowledge-graph memory (entities, relations, observations) as JSONL |
shell |
mcp-shell |
Execute local programs directly with a restricted working directory |
skills |
mcp-skills |
Discover and progressively load workspace skill instructions |
agents |
mcp-agents |
Run configured workspace subagents through external model providers |
Built on the official Rust SDK (rmcp 3.1). The 2026-07-28 protocol is
stateless: server/discover without an initialize handshake, cache hints
on tools/list, and per-tool annotations.
Full documentation: https://maxylev.github.io/modelcontextprotocol/ (usage, CLI reference, protocol details, security model, tool reference for all 29 tools, coverage matrix, and CI/CD notes).
Installation
One-line installer (macOS / Linux / Android)
|
The script detects your OS and CPU, downloads the matching prebuilt binary
(MSRV build), verifies its SHA-256 checksum, and installs it to
~/.local/bin ($PREFIX/bin under Termux). Override the directory with
INSTALL_DIR:
| INSTALL_DIR=/usr/local/bin
Requires curl, tar, and sha256sum (Linux/Android) or shasum (macOS).
The script itself is in the repository root (install.sh).
Prebuilt binaries (no Rust required)
Every v* tag publishes prebuilt binaries to
GitHub Releases.
No Rust or Cargo needed: download your platform's archive below, extract it,
and put the modelcontextprotocol executable in your bin folder (or
anywhere on your PATH).
Direct links to the latest version of each package (replace
rust-msrv with rust-stable for the build made with the latest stable
Rust):
The -musl Linux builds are fully static and run on any distribution; the
Windows builds link the CRT statically (no VC++ runtime needed). Not sure
about your architecture? Run uname -m (macOS/Linux) or echo %PROCESSOR_ARCHITECTURE% (Windows). Every release ships a .sha256
checksum file named after the archive base — e.g.
modelcontextprotocol-aarch64-apple-darwin-rust-msrv.sha256 — covering the
archive and the install.sh script.
Install on macOS
(On Intel Macs, use the x86_64-apple-darwin archive above.)
Install on Linux
(The static musl build works on every x86_64 distribution. On aarch64
devices — Raspberry Pi 4/5, Apple Silicon VMs — use the
aarch64-unknown-linux-musl archive, or armv7-unknown-linux-musleabihf
on 32-bit ARM.)
Install on Windows (PowerShell)
Invoke-WebRequest -Uri "https://github.com/maxylev/modelcontextprotocol/releases/latest/download/modelcontextprotocol-x86_64-pc-windows-msvc-rust-msrv.zip" -OutFile modelcontextprotocol.zip
Expand-Archive modelcontextprotocol.zip -DestinationPath modelcontextprotocol
New-Item -ItemType Directory -Force -Path "$HOME\bin" | Out-Null
Move-Item modelcontextprotocol\modelcontextprotocol.exe "$HOME\bin\"
Then add %USERPROFILE%\bin to your PATH (System Properties → Environment
Variables, or setx PATH "%PATH%;%USERPROFILE%\bin" and reopen the
terminal).
Install on Android (Termux)
Verify a download
# macOS / Linux — download the archive, its checksum, and the installer,
# then verify all three against the release checksum file
# Windows PowerShell
iOS note: the iOS archive is an unsigned Mach-O binary. iOS has no user-installable
binfolder, so it cannot be run on a device as-is; it is provided for signing and embedding into an app.
From source
Or install directly from the repository:
The release binary is about 6.5 MB on macOS (size varies by target). Building from source requires Rust 1.97+ (MSRV); the prebuilt binaries above run on Linux / macOS / Windows / Android.
Quick start
Both a subcommand form and an equivalent flag form are supported so the binary fits any MCP client. Subcommand form (recommended):
When no directory is supplied, filesystem, shell, skills, and agents
use the MCP server process's current directory. This lets a project-local MCP
configuration follow the directory in which the client launches its servers.
Pass explicit directories when the client does not launch MCP servers from the
workspace or when filesystem/shell should allow multiple roots.
Flag form (--filesystem [DIR ...], --fetch, --memory,
--shell [DIR ...], --skills [DIR], --agents [DIR])
is equivalent. See the CLI reference
for all options, conflict rules, and environment variables.
Agent credentials are supplied to the same binary through each definition's
env_key: OpenAI and Anthropic definitions default to OPENAI_API_KEY and
ANTHROPIC_API_KEY; a custom definition can use OPENROUTER_API_KEY or
another environment variable. Do not put credentials in agent files.
Adding to your MCP client
A tutorial with the exact config file, format, and commands for each client is in the docs: Adding the servers to your MCP client.
Covered clients:
| Client | How to configure |
|---|---|
| opencode v1/v2 | mcp key in opencode.json / opencode.jsonc, or opencode mcp add |
| Claude Desktop | mcpServers in claude_desktop_config.json |
| Claude Code | claude mcp add <name> -- modelcontextprotocol ..., or .mcp.json |
| Codex CLI | [mcp_servers.*] in ~/.codex/config.toml, or codex mcp add |
| Pi agent | pi install npm:pi-mcp-adapter, then mcpServers in .mcp.json / ~/.pi/agent/mcp.json |
| Gemini CLI | mcpServers in ~/.gemini/settings.json, or gemini mcp add |
| Cursor | mcpServers in .cursor/mcp.json / ~/.cursor/mcp.json |
| Windsurf, Zed, VS Code, Continue, Cline, Roo | see the tutorial table |
Validate
Quick smoke test with a generic MCP client: start
modelcontextprotocol memory --memory-file /tmp/smoke.jsonl, list tools
(9 memory tools), call create_entities, call read_graph. More in the
verification guide.
Security — read before you trust
- Shell server: executes arbitrary local programs with the OS permissions of the MCP server process. The working-directory restriction is not a sandbox, and there is no command filter. Only connect it to clients you trust.
- Fetch server: can reach local and internal network addresses (no SSRF protection); only enable it for trusted clients. Requests are bounded by a 30-second timeout and robots.txt policy.
- Filesystem access is restricted to configured directories with symlink protection — workspace access control, not an OS sandbox.
- Context-window protection: tool results are size-bounded so a single
call cannot overflow the client context.
directory_treeis capped at 1024 entries (atruncatedmarker entry is included when the budget is exhausted, and the JSON itself is truncated at 64 KiB with a notice when entry names are long), text results (read_text_file,read_multiple_files,search_files,list_directory,list_directory_with_sizes,edit_file) are truncated at 64 KiB with a notice explaining how to get the rest, andread_media_filerefuses files over 1 MiB. UseexcludePatterns/head/tailto keep results inside the limits. - Skills server: skill files are repository instructions. Activation loads instructions and resource paths only; it does not automatically execute instructions or resources.
- Agents server: agents can call external providers and configured child
tools or commands. Enable it only for a trusted workspace. Provider secrets
are read from the environment variable named by each agent's
env_key; never place keys in agent definitions. - See the security model for details.
Development
A gated, real-network acceptance suite (tests/openrouter_e2e.rs, ignored
by default) drives the filesystem, fetch, memory, and shell catalogs through
real OpenRouter roundtrips. The agents provider smoke test is documented
separately in the verification guide. Both require OPENROUTER_API_KEY and
spend tokens. Run the original catalog suite with:
OPENROUTER_API_KEY=<key
Docs site: cd docs && npm install, then npm run docs:dev (dev) or
npm run docs:build (build; output in docs/.vitepress/dist). Docs gates
are npm run format:check and npm run docs:build.
Repository layout
src/— the binary:cli.rs(CLI),fs/,fetch/,memory/,shell/,skills/, andagents/(servers),support/(shared helpers).tests/— integration suites per server plus the gated OpenRouter E2E harness (openrouter/).docs/— VitePress documentation site (deployed to GitHub Pages)..github/workflows/— CI (lint + test matrix), docs publishing, and crates.io publishing workflows.
License
MIT