Mafsil MCP server
Commit Nov 2, 2026Connect AI agents to a local workspace for precise file editing, command execution, and interactive terminal sessions on Windows and Linux.
Also known as AMD4x/Mafsil
- Stars
- 1
- Tools
- 9
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 2, 2026
- License
- MIT
What is Mafsil MCP?
Mafsil connects AI agents to a local workspace for precise file editing, command execution, and interactive terminal sessions on Windows and Linux. It exposes 9 tools, such as server_info, list_directory, read_file.
Summary generated from the project's README
About Mafsil MCP server
Connecting AI agents to a local project folder on Windows or Linux is what Mafsil enables. It allows developers to grant agents the ability to read files, perform precise edits, and run commands within a specific workspace. The server operates as a local stdio process, meaning it requires no inbound network ports or background services to function.
Users can control agent capabilities through a configuration file that toggles write access and command execution. By default, the server is read-only, providing a layer of safety. When enabled, tools like edit_files allow for revision-checked changes across multiple files, while exec_command and session_io provide access to interactive terminals using native PTY or ConPTY technology. This setup is designed for developers who need an agent to interact directly with their existing codebases and development environments.
What you can do with it
- 1Perform precise code modificationsAsk an AI agent to apply specific, revision-checked edits across multiple files in your project.
- 2Manage interactive terminal sessionsHave an AI agent run commands and interact with a live shell directly in your workspace.
- 3Audit workspace contentsInstruct an agent to list directory entries and read text or image files from a local folder.
- 4Monitor command execution outputUse an AI client to replay command output or take snapshots of a terminal screen.
Written from the project's README. Every use case is checked against a quote from it.
Mafsil MCP tools 9
Detected from the READMEserver_infolist_directoryread_fileedit_filescreate_directoryexec_commandsession_iolist_sessionsclose_session
Configuration
MAFSIL_HOME
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableamd4x/mafsil is public and reachablegithub.com/amd4x/mafsil ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-02github.com/amd4x/mafsil ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model9 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMafsil connects an MCP-compatible agent to a workspace on Windows or Linux. Read files, make precise conditional edits, run commands, and work with interactive terminals through a small set of composable tools.
Read only by default. You choose the workspace and separately enable file changes and command execution. Mafsil runs as a local stdio process, needs no inbound network port, and starts no background service.
Available for Windows x64, Linux x64 and Linux ARM64. Download the latest release or use the installers below. Native CI validates all three targets; see validation status.
What it does
- Reads bounded UTF-8 text, images and embedded file resources.
- Applies exact, revision-checked edits across multiple files, with prevalidation and rollback on IO failure.
- Runs ordinary commands and interactive shells using native ConPTY on Windows and PTY on Linux.
- Retains bounded process output with replay offsets, cancellation, timeouts, terminal resize and plain-text screen snapshots.
- Speaks MCP
2026-07-28and the four earlier revisions supported by the official Go SDK.
The name comes from the Arabic مَفْصِل, a point where two parts connect.
Get started
Install or update Mafsil
Run one command for your platform. It selects the latest stable release and verifies the release installer before running it. Installation does not choose a workspace or change your projects.
Windows — PowerShell 7
irm https://raw.githubusercontent.com/AMD4x/Mafsil/main/install.ps1 -ErrorAction Stop | iex
Linux — Bash, x64 / ARM64
(set -o pipefail; curl --proto '=https' -fsSL https://raw.githubusercontent.com/AMD4x/Mafsil/main/install.sh | sh)
To update later, close your MCP clients and run the same command again. Your configuration and workspace files are preserved. There is no background updater or persistent PATH change. See the installation guide for version pinning, custom locations, status and uninstall.
Choose an existing workspace
Your workspace is your own existing project folder, wherever you keep it. No particular drive or folder name is required. The commands below ask for its full path; they do not create or move that folder.
Mafsil keeps its executable and configuration together in its own directory. Keep that directory outside the workspace you expose to an agent.
Windows — PowerShell 7
$MafsilHome = Join-Path $env:LOCALAPPDATA 'Programs\Mafsil'
$Workspace = Read-Host 'Full path to your existing workspace folder'
& "$MafsilHome\mafsil.exe" init --workspace "$Workspace" --output "$MafsilHome\config.json"
& "$MafsilHome\mafsil.exe" doctor --config "$MafsilHome\config.json"
Linux — Bash
MAFSIL_HOME="$HOME/.local/share/mafsil"
read -r -p 'Full path to your existing workspace folder: ' MAFSIL_WORKSPACE
"$MAFSIL_HOME/mafsil" init --workspace "$MAFSIL_WORKSPACE" --output "$MAFSIL_HOME/config.json"
"$MAFSIL_HOME/mafsil" doctor --config "$MAFSIL_HOME/config.json"
For a custom installation or source build, set MafsilHome / MAFSIL_HOME to the directory containing your executable. Run init once: it refuses an existing configuration rather than overwriting it. doctor checks configuration without running commands or connecting to a network service.
Connect an MCP client
Use an absolute executable path and an absolute configuration path in your client's stdio MCP settings:
{
"mcpServers": {
"mafsil": {
"command": "/absolute/path/to/Mafsil/mafsil",
"args": ["serve", "--config", "/absolute/path/to/Mafsil/config.json"]
}
}
}
Replace both paths with the executable and config.json in your Mafsil directory. On Windows use mafsil.exe and escape each backslash as \\ in JSON, or use forward slashes. Some clients use a different settings structure; the command and arguments stay the same.
Start with server_info, list_directory and read_file. The client owns the stdio process lifetime. Disconnecting closes managed sessions.
Enable the capabilities you need
Edit the generated configuration:
{
"workspace": "/path/to/workspace",
"allowWrite": true,
"allowExec": false
}
Omitted limits use conservative defaults. Enable execution only for a trusted client and a suitable user account:
{
"workspace": "/path/to/workspace",
"allowWrite": true,
"allowExec": true,
"scratchDirectory": "/absolute/path/to/Mafsil/scratch"
}
Restart the client connection after changing capabilities. Execution can modify files outside the workspace, access the network, and read anything the server's user can read. The filesystem boundary applies to file tools; it is not an execution sandbox. Use a dedicated OS account or an independently configured isolation environment when you need stronger separation.
Tools
| Tool | Purpose | Available when |
|---|---|---|
server_info |
Version, capabilities and limits | Always |
list_directory |
Bounded, paged directory entries | Always |
read_file |
Text, image or embedded resource, with SHA-256 | Always |
edit_files |
Conditional write, exact edit, move or delete | allowWrite |
create_directory |
Create one directory | allowWrite |
exec_command |
Command, program or interactive shell | allowExec |
session_io |
Output replay, input, EOF and resize | allowExec |
list_sessions |
Session status | allowExec |
close_session |
Stop a managed process tree | allowExec |
See tool contracts and examples and configuration.
Installation and updates
The terminal installers select the latest stable release, download the correct binary and verify its SHA-256. They run without administrator/root elevation, preserve configurations and unrelated files, and roll back ordinary update failures. Re-running the installer updates the managed files. The same script provides status and uninstall commands.
There is no automatic update, service registration, persistent PATH edit, or startup integration. Release binaries carry Windows version/icon resources and are distributed separately for Windows amd64, Linux amd64 and Linux arm64.
Optional OpenAI integration
Mafsil can be the local stdio server behind the official Secure MCP Tunnel client. Tunnel identity, authentication, upgrades and deployment belong to that client. Mafsil stores no tunnel credentials. See the integration guide, including the limits of local verification.
Security boundaries
File tools use Go's traversal-resistant os.Root, reject links/reparse points and hard-linked files, and enforce file, request and output limits. Updates require the exact revision you read. Multi-file edits are not crash-atomic; cancellation after commit begins requires a read-back to determine the outcome.
Command children receive an allowlisted environment with dedicated temporary paths. Windows processes join a kill-on-close Job Object before execution. Linux uses process groups; deliberate daemonization or privilege changes can escape that lifecycle mechanism. Screen snapshots are an approximation; raw VT output is also available.
Read the threat model before enabling execution. Report vulnerabilities using SECURITY.md.
Help and feedback
Report a bug, ask for help or suggest an improvement. The forms help you include your Mafsil version, platform and a small reproduction. Search existing issues first, and remove private paths, files and credentials from anything you share.
For vulnerabilities, use private security reporting instead of a public issue. See SECURITY.md for the reporting scope.
Development
Build from source
Go 1.27.3 or later is needed to build, not to use a release binary. Windows shell execution uses PowerShell 7; Linux shell execution uses Bash. File tools do not require a shell.
Windows, from the source directory:
go build -trimpath -o ..\mafsil-build\mafsil.exe .\cmd\mafsil
& ..\mafsil-build\mafsil.exe version
Linux:
go build -trimpath -o ../mafsil-build/mafsil ./cmd/mafsil
../mafsil-build/mafsil version
Then follow workspace setup, using the build directory as your Mafsil directory. Building the executable does not configure a workspace.
Verify changes
python scripts/verify.py --security
Use --race where a C compiler is available. CONTRIBUTING.md explains fixtures, native tests, fuzzing, packaging and dependency notices. CI runs native Windows amd64, Linux amd64 and Linux arm64 checks; releases are published manually from a successful CI run for the selected source commit and verified manifest.
Mafsil's code and original brand assets use the MIT license. Dependencies retain the licenses reproduced in THIRD_PARTY_NOTICES.md.
Mafsil MCP questions
What tools does Mafsil MCP provide?
It exposes 9 tools, including server_info, list_directory, read_file, edit_files, create_directory.
What operating systems does Mafsil support?
Mafsil is available for Windows x64, Linux x64, and Linux ARM64.
Is the server read-only by default?
Yes, the server is read-only by default; you must explicitly enable file changes and command execution in the configuration.
Does Mafsil require a background service or network port?
No, it runs as a local stdio process and does not require an inbound network port or a background service.