Rust MCP Server

Overview

Rust MCP Server is a high-performance Model Context Protocol (MCP) server implementation built with Rust. It provides a comprehensive set of tools for AI assistants to interact with the file system, execute commands, make HTTP requests, and more - all through a modern WebUI control panel.

Demo Screenshots

Features

Core Features

• 20 Built-in Tools: File operations, Office document support via a dedicated Office tool (27 operations over .docx/.pptx/.xlsx/.pdf/.ipynb, including PDF page operations, encrypted-PDF read/edit and markdown→PDF creation), PDF page-to-image rendering with an embedded PDFium payload (chromium/7881) and a pdfium → pdftoppm → embedded-image fallback chain, HTTP requests, full Git operations on a built-in libgit2 engine (read/write/network, no system git required), Python execution (embedded RustPython; 48 frozen third-party pure-Python distributions), archive, diff, note storage, task management, web search, notebook editing, command monitoring, and more
• Tool Presets: 6 built-in presets (minimal, coding, data_analysis, system_admin, research, full_power) for one-click tool configuration
• System Prompt: Custom instructions appended to MCP initialize response via --system-prompt or WebUI
• WebUI Control Panel: Cyberpunk AI Command Center theme with glassmorphism HUD, animated background, terminal log stream, and 3D card tilt effects
• Real-time Updates: SSE-based live status updates in WebUI
• System Metrics: Real-time CPU, memory, and load monitoring via HUD and /api/system-metrics endpoint
• Streamable HTTP Transport: the only transport; stateless + JSON responses; the legacy SSE transport was removed in 0.5.0
• Concurrency Control: Configurable max concurrent tool calls
• Internationalization: Support for English and Chinese

Security Features

• Working Directory Restriction: Write operations restricted to configured directory; read-only tools can access any path (intentional design for system-level code analysis)
• Dangerous Command Blacklist: 20 configurable dangerous command patterns
• Script Execution Heuristics: Flags script-file wrappers and evasion forms
• Two-Step Confirmation: Dangerous and script-like commands require user confirmation
• Audit Logging: All command executions are logged
• Injection-Pattern Detection Removed: Shell operators (;, |, &, command substitution, redirection) no longer trigger confirmation — an accepted design trade-off

Available Tools

File Operations (Safe / Enabled by Default)

The following read-only tools are not restricted to the working directory:

File Operations (Dangerous / Disabled by Default)

The following write operations are restricted to the working directory:

System & Network Tools

Utility Tools

Task, Web & Interaction Tools

Office & Monitoring Tools

Quick Start

Installation

Option 1: Download Pre-built Binary

Download the latest release from GitHub Releases.

Option 2: Build from Source

# Clone the repository
git clone https://github.com/yuunnn-w/Rust-MCP-Server.git
cd Rust-MCP-Server

# Build using the provided script
# On Linux/macOS:
./scripts/build-unix.sh

# On Windows:
.\scripts\build-windows.bat

# Or build manually with cargo
cargo build --release

Note: PDF page rendering embeds a PDFium payload for Windows x64/x86 builds (assets/pdfium/{x64,x86}/pdfium.dll.zst, chromium/7881). Other targets (including ARM64, Apple Silicon and ARM64 Linux) build with an empty payload and fall back to pdftoppm/embedded-image extraction at runtime.

Asset Dependencies

The project includes several pre-bundled assets and relies on build.rs to auto-download others at build time. Below is a complete reference.

Bundled Assets (committed to git)

Build-Time PDFium Pipeline (build.rs)

• A downloaded archive is a build cache, not a source file: only the .dll.zst payloads are committed to git, and the working .dll is ignored.
• Missing assets fail the build with an actionable message (exact path, upstream URL, expected hash). Set RUST_MCP_PDFIUM_OPTIONAL=1 to build without the payload deliberately (the runtime then degrades to the fallback chain).
• At runtime the payload is extracted to a per-user temp cache directory, re-hashed on every install (including cache hits), and rejected on any mismatch.

Note: If the fallback download fails (e.g., no network, GitHub rate limit), build.rs prints the same actionable instructions; you can also place the DLL or its .tgz archive in assets/pdfium/{arch}/ manually.

Windows 7 Compatibility Assets (Required for Win7 Target Only)

Only needed when building with --target x86_64-win7-windows-msvc:

Windows 7 Compatibility

The server can run natively on Windows 7 without third-party compatibility layers (e.g., VxKex). This is achieved through two embedded compatibility layers:

• VC-LTL5 v5.3.1 (assets/vc-ltl/) — replaces the UCRT/VCRUNTIME CRT with msvcrt.dll, eliminating api-ms-win-crt-* and VCRUNTIME140.dll imports that don't exist on Windows 7
• YY-Thunks v1.2.2 (assets/yy-thunks/) — provides runtime stubs for Windows 8+ APIs (e.g., GetSystemTimePreciseAsFileTime, WaitOnAddress, ProcessPrng), falling back to older equivalents

Both are injected at link time via build.rs. The project is fully self-contained — no external downloads required.

To build for Windows 7:

rustup update nightly
cargo +nightly build -Z build-std=std,panic_abort --target x86_64-win7-windows-msvc --release

Note: On Windows 7, the system_info tool automatically returns limited information (CPU, memory, and OS basics) and skips disk, network, and hardware temperature enumeration to avoid compatibility issues with the sysinfo crate.

Usage

# Start with default settings (HTTP transport + WebUI)
./rust-mcp-server

# Start with custom WebUI port
./rust-mcp-server --webui-port 8080

# Enable dangerous commands (by ID)
./rust-mcp-server --allow-dangerous-commands 1,2

# See all options
./rust-mcp-server --help

Access WebUI

Once started, open your browser:

http://127.0.0.1:2233

Browser requirement: the WebUI requires a modern browser with ES2020 support (Chrome 79+ / Edge 79+). On Windows 7, please use a recent Chromium-based browser; older browsers (e.g. IE11) will only show an upgrade prompt instead of the interface.

Configuration

Command Line Options

Configuration Persistence: The server loads configuration from multiple sources with the following priority (highest to lowest):

1. CLI arguments — explicitly provided flags always take precedence
2. config.json in the executable directory — loaded if present, but only fields explicitly present in the file override lower-priority sources
3. Environment variables — used when neither CLI nor config.json provides a value
4. Built-in defaults — lowest priority

Runtime changes made via the WebUI or API are persisted to config.json immediately.

Tool Presets: The server starts with the minimal preset by default. Use --preset <name> to choose a different preset, or --preset none to skip auto-applying.

• minimal (7 tools): Safe read-only tools + sandboxed Python
• coding (18 tools): Development-focused, includes file editing, task management, and command execution
• data_analysis (14 tools): Data analysis, includes Python, diff, archive, and web tools
• system_admin (17 tools): System administration, includes system info, processes, commands, and file operations
• research (9 tools): Research and documentation, includes web search, web fetch, and file reading
• full_power (20 tools): All tools enabled

Dangerous Command IDs

The following commands are blocked by default and require explicit permission:

Enable with: --allow-dangerous-commands 1,3,5

Security

Command Execution Security

The Bash tool implements multiple security layers:

1. Working Directory Restriction: Commands can only operate within the configured working directory
2. Dangerous Command Blacklist: Blocks known dangerous commands (see list above)
3. Script Execution Heuristics: Flags interpreter/script-file wrappers (e.g. sh evil.sh, cmd /C evil.bat, source file, . file, commands starting with backticks) and evasion forms (bare tabs, wide Unicode whitespace, $IFS)
4. Two-Step Confirmation: Commands hitting the blacklist or heuristics require user confirmation via repeated call
5. Audit Logging: All commands are logged with timestamp and result

Command injection pattern detection (shell metacharacters such as ;, |, &, backticks, $) has been removed by design — commands containing these operators generally execute directly without confirmation. Also, the blacklist is mostly anchored on the leading prefix (a few pure-substring patterns, such as the fork bomb, are not position-limited), so a dangerous primitive not in first position (e.g. echo ok; rm -rf /) is not caught by it; mitigations remain: [AUDIT] logging for every command, Bash disabled by default, and WebUI tool toggling.

WebUI Authentication

When --webui-token is configured, most WebUI endpoints require an Authorization: Bearer <token> header (Bearer prefix is case-insensitive). The following endpoints remain open without authentication:

• GET /api/tools — list all tools
• GET /api/status — tool status alias (deprecated, use /api/v1/tools)
• GET /api/tool-presets — list presets
• GET /api/python-fs-access — check Python FS access status
• GET /api/v1/events — SSE stream

All other endpoints (including most GET endpoints such as /api/config, /api/system-metrics, /api/tool/{name}/stats, /api/version, and all mutating endpoints) require a valid Bearer token.

File Operation Security

Read-only tools (Glob, Read, Grep, Office read) and the Git tool's read actions can access paths outside the working directory. This is intentional design to facilitate system-level code analysis. Git write/network actions are restricted to the working directory and disabled by default; write/edit/delete tools remain strictly restricted to the working directory:

• Path traversal attacks (../etc/passwd) are blocked for write operations
• Symbolic link escaping is prevented for write operations
• Absolute paths outside working directory are rejected for write operations

Example Security Flow

User: Bash("rm -rf /")
Server: "Security Warning: Dangerous command 'rm (delete files)' detected.
        This command may cause damage to the system or data.
        Please confirm with the user whether to execute this command.
        If the user agrees, please call the Bash tool again."

User: Bash("rm -rf /")  [Second call within 5 minutes]
Server: [Command executed after confirmation]

Documentation

• API Documentation - REST API reference
• Architecture - System architecture and design
• User Guide - Detailed user guide
• Security Guide - Security features and best practices
• Windows 7 Compatibility Guide - Building native Windows 7 binaries (VC-LTL5 + YY-Thunks), principles-first
• Contributing - Contribution guidelines

Development

Project Structure

Rust-MCP-Server/
├── src/
│   ├── main.rs              # Entry point
│   ├── config.rs            # Configuration management
│   ├── mcp/
│   │   ├── handler.rs       # MCP protocol handler
│   │   ├── state.rs         # Shared server state
│   │   └── tools/           # Tool implementations
│   ├── utils/               # Utility functions (file, image, system metrics, office conversion)
│   │   ├── office_converter.rs  # Office document conversion (docx-rs, lopdf, calamine, LibreOffice)
│   │   ├── office_utils.rs      # Office document utility functions
│   └── web/                 # WebUI and HTTP API
├── scripts/                 # Build scripts
├── docs/                    # Documentation
├── README.md               # This file
├── README-zh.md            # Chinese README
└── LICENSE                 # GPL v3.0 License

Testing with llama.cpp

You can test the MCP server using llama.cpp's llama-server which supports MCP via WebUI configuration.

# 1. Start the MCP server
./rust-mcp-server --mcp-port 8080

# 2. Start llama-server
llama-server -m your-model.gguf

# 3. Open llama.cpp WebUI, go to Settings and configure MCP server URL
#    (e.g., http://localhost:8080)

# 4. Enable MCP tools and start chatting

Note: llama.cpp provides experimental MCP CORS proxy support via --webui-mcp-proxy flag. See llama.cpp documentation for details and security considerations.

Building Documentation

cargo doc --no-deps --open

Changelog

See CHANGELOG.md for version history and changes.

Contributing

Contributions are welcome! Please read our Contributing Guidelines before submitting PRs.

License

This project is licensed under the GPL v3.0 License - see the LICENSE file for details.

Acknowledgments

• Model Context Protocol - The protocol specification
• rmcp - Official Rust MCP SDK
• Axum - Web framework for Rust
• Tokio - Async runtime for Rust

Support

• GitHub Issues: Report bugs or request features
• GitHub Discussions: Ask questions or share ideas