MCP-RS Documentation
Welcome to the MCP-RS documentation! This site contains comprehensive guides, API references, and architecture documentation for the Rust implementation of the Model Context Protocol.
Quick Access
- Getting Started - Implementation guides and tutorials
- API Reference - Complete API documentation
- Architecture - System design and technical architecture
Documentation Hub
- Full Documentation - Complete documentation index
- GitHub Repository - Source code and issues
What is MCP-RS?
MCP-RS is a Model Context Protocol (MCP) server written in Rust. MCP clients such as Claude Desktop and Claude Code connect to it over STDIO, and other clients over HTTP, to use tools for WordPress, a PostgreSQL database, and external MCP servers added as plugins.
Key Features
๐ Core Capabilities
- MCP over JSON-RPC 2.0: Protocol versions up to 2025-11-25
- Request Dispatch:
McpServerlists tools from every handler and routes each call to the handler that provides it, in both STDIO and HTTP modes - Transports: STDIO, and HTTP (with optional WebSocket on
/ws) - Plugins: Add the tools of any MCP server that speaks STDIO, run as a child process, in a Docker container, or as a Kubernetes Job. See Plugins
- Configuration: One TOML file, with
${VAR}for values from environment variables - Status Tool:
mcp_rs_statusshows the version, config file, log files, and what failed to start
๐ Security Features
- Encrypted Credentials: The WordPress Application Password can be stored encrypted with AES-GCM-256 (PBKDF2 key derivation), or read from an environment variable
- HTTP Mode Authentication: API keys, or OAuth 2.1 access tokens issued by an external authorization server
- Per-Caller Tool Limits: Allow each API key or token only the tools it needs (for example
@read_only) - TLS/mTLS: HTTPS with a minimum TLS version, and optional client certificates
- Rate Limiting of WordPress and plugin tool calls
- Audit Logging: Who called which tool, and the result
See Security for the settings.
๐ฏ WordPress MCP Tools (32 tools available)
๐ Content Management:
- Create, read (full editable source), update, and delete posts and pages
- Advanced post creation with SEO and scheduling
- YouTube and social media embeds
- Category and tag management
๐ผ๏ธ Media Management:
- Upload media files (base64, with type, extension, and content validation)
- Featured image management
- Media library operations
- Accessibility support (alt text, captions)
๐ Content Integration:
- Create posts with taxonomy
- Comment retrieval
โ๏ธ Site Management:
- Read and update site settings
- Front page configuration
- Health check of connectivity, authentication, and permissions
See WordPress Integration for the full list of tools.
๐๏ธ Database MCP Tools (PostgreSQL)
execute_query: OneSELECT, run in a read-only transaction that is rolled backget_schema: Tables, columns, keys, and indexesexecute_command: OneINSERT,UPDATE, orDELETE, only withallow_write = true- Values are bound as parameters; results are limited in rows and time
See Database Integration for the settings.
Current Status
โ Recently Completed (v0.25.0)
- ๐ฌ MySQL and MariaDB:
[database]now also connects to MySQL (engine = "mysql", 8.0 or later) and MariaDB (engine = "mariadb", 10.6 or later), with the same tools and limits as PostgreSQL: read-only by default,?parameters, time, row and size limits, and TLS. See Database Integration - ๐ฆ Ready-Built Files: Each release now has mcp-rs for Windows (x64), macOS (Apple Silicon), and Linux (x64), with SHA256 checksums, so Rust is not needed. See the README
- ๐ฉบ
mcp-rs check: Checks a config file without an MCP client: whether it loads, whether the WordPress credentials can be read, and whether mcp-rs can reach the site and sign in - ๐งฉ VS Code (GitHub Copilot): How to use mcp-rs from the Copilot chat in VS Code
โ v0.24.0
- ๐ OS Credential Store: WordPress credentials can come from the Windows Credential Manager, the macOS Keychain, or the Linux Secret Service (
keyring = "<name>", registered withmcp-rs wordpress-keyring set), so Claude Desktop, Claude Code, and a terminal all read the same place. The entry remembers its site and is used only for thaturl. See Security - ๐ Security Review: A review of the whole server. HTTP mode no longer starts on a network address without authentication, limits connections, request sizes and times, and closes idle and stalled WebSocket connections. Without
--config, mcp-rs no longer reads a config file in the current folder. Logs are private to your user, database results are limited in size, and headers from a reverse proxy are used only fromtrusted_proxies. See Security - ๐งน Config Examples: Every example under
configs/now loads in the current format, and a test keeps them that way
โ v0.23.0
- ๐๏ธ Database Tools: Add a
[database]section to connect one PostgreSQL database.execute_query(SELECT) andget_schemaare always available, andexecute_command(INSERT, UPDATE, DELETE) only withallow_write = true. Queries run in a read-only transaction that is rolled back, values are bound as parameters, and results are limited in rows and time. Included in the default build. See Database Integration - ๐ณ Docker Image: The image now starts with its default arguments. Mount a config file at
/app/config/mcp-config.toml; see the Docker guide - ๐งน Honest Code and Docs: Removed settings and arguments that were accepted but never used (such as
PasswordHasher::new(salt_rounds)), a module whose health checks always reported success, and documentation that described features mcp-rs does not have
โ v0.22.0
- ๐ MCP Protocol 2025-11-25: Clients that ask for the newest protocol version, such as Claude Desktop, now get it. Clients using
2025-06-18or2024-11-05keep working as before - ๐ Requests from Web Pages: In HTTP mode, mcp-rs checks the
Originheader and answers requests from web pages on other origins with 403, so a page you visit cannot call its tools through your browser. CORS follows the same rule, andallowed_originsadds origins. See Security - ๐ Audit Log Location: The audit log is now written next to the logs, to
%USERPROFILE%\.mcp-rs\audit\audit.logon Windows, and on Linux and macOS it is readable by your user only. The oldaudit.lognext to the config file is left in place
โ v0.21.0
- ๐ Log Files by Local Date: Log files now switch at local midnight, so the date in the file name matches the times in the log. When a running mcp-rs switches to a new file, it writes a
continuedline with itspidandinstanceat the top - ๐ Which Process Did It: Each audit log record has
pidandinstanceinmetadata, matching the logโs header lines and theInstanceline ofmcp_rs_status, so you can tell the two processes Claude Desktop starts apart - ๐ Dependencies: jsonwebtoken 11.1 with the
aws_lc_rsbackend, the same crypto library rustls already uses
โ v0.20.0
- ๐งน Cleanup: Removed modules, features, and dependencies that the server never used (725 โ 591 crates; OpenSSL is no longer needed), and corrected the documentation to match what mcp-rs actually does
- ๐ Environment Variables in the Config File: Values expanded from
${VAR}are no longer written to the debug log. With WordPress enabled, mcp-rs does not start when a referenced variable is missing, and names the setting and the variable. See Security - ๐ Log Location: When installed in
C:\Program Files\MCP-rs, the log in%USERPROFILE%\.mcp-rs\logsis no longer reported as a fallback
โ v0.19.2
- ๐ฉบ Status Tool: Ask your AI client to call
mcp_rs_statusto see the version, the config file in use, where the log and audit log are written, and the state of each plugin. See API - ๐ Unknown Options: mcp-rs no longer starts with an unknown option or
--configwithout a path, so a typo does not silently use another config file
โ v0.19.1
- ๐ท๏ธ Version and Help:
mcp-rs --versionprints the installed version, andmcp-rs --helplists the options
โ v0.19.0
- ๐ OAuth 2.1 for HTTP Mode: Accept access tokens from an external authorization server such as Keycloak, Okta, or Microsoft Entra ID, as described in the MCP specification. See Security
- ๐งฐ Tools per API Key or Token: Limit which tools each API key or OAuth scope may use, for example read-only tools only. See Security
- ๐ Audit Log: Choose where the audit log is written (by default, next to the config file), with rotation. Every tool call is recorded with the caller, result, and duration. See Security
- ๐ MCP Protocol 2025-06-18: Tool annotations (read-only, destructive),
outputSchema, andstructuredContentare passed on to clients that use the new version - ๐ฆ Plugins in Containers and Kubernetes: Run a plugin in a Docker container or as a Kubernetes Job, with no network access by default. See Plugins
โ v0.18.4
- ๐ HTTP Mode Works: Requests over HTTP (
/mcp) and WebSocket (/ws) are now answered, with the same tools as STDIO mode, including plugins. Previously every request timed out - ๐ Concurrent Clients: Each HTTP request gets its own response, even when several clients use the same JSON-RPC
id
โ v0.18.3
- ๐ Plugins: Add tools from other MCP servers, run as separate processes. mcp-rs relays them as
<plugin>__<tool>with rate limiting, audit logging, and timeouts (STDIO mode). See Plugins - ๐ Post Slugs: Set the URL slug when creating or updating a post or page, for example an English slug for a Japanese title
- ๐งฉ Multiple Handlers in STDIO Mode: Tools from all handlers are listed and each call goes to the handler that provides the tool
โ v0.18.2
- ๐ Safer Retries: Create and delete requests to WordPress are no longer resent after a timeout or 5xx error, so media is not uploaded twice
- ๐งน Cleanup: Removed unused modules that were never connected to the server (interactive setup,
src/k8s, and the earlier plugin implementations)
โ v0.18.1
- ๐ผ๏ธ Upload Local Files:
upload_mediacan read a file from folders allowed inupload_allowed_dirs, instead of base64 data - ๐ Featured Image in
get_post: Shows the featured imageโs media ID and URL - ๐ Full Post Content in
get_post: Returns the whole content, including the editable source with Gutenberg block markup - ๐ Credential Encryption Command:
mcp-rs encrypt-wordpress-credentialsgenerates theencrypted_credentialssection - ๐ MCP Protocol Fixes: STDIO and HTTP no longer answer JSON-RPC notifications
- ๐๏ธ Media Deletion Fix:
delete_mediawithforce: trueno longer reports an error after deleting
โ v0.18.0
- ๐ API Key Authentication: Optional API key check on every HTTP/WebSocket request
- ๐ฆ Rate Limiting: WordPress tool calls are rate limited per site
- ๐ Audit Logging: Every WordPress tool call that changes the site is recorded, including rejected ones
- ๐ Encrypted Credentials: WordPress Application Passwords can be stored encrypted in the config file
- ๐ผ๏ธ Media Upload Validation: MIME allowlist, extension and content checks, and size limits for
upload_media - ๐ก๏ธ Dependency Audits: Known vulnerabilities fixed, and
cargo auditnow runs daily
See the Security documentation for details.