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

Documentation Hub

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: McpServer lists 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_status shows 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: One SELECT, run in a read-only transaction that is rolled back
  • get_schema: Tables, columns, keys, and indexes
  • execute_command: One INSERT, UPDATE, or DELETE, only with allow_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 with mcp-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 that url. 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 from trusted_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) and get_schema are always available, and execute_command (INSERT, UPDATE, DELETE) only with allow_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-18 or 2024-11-05 keep working as before
  • ๐Ÿ” Requests from Web Pages: In HTTP mode, mcp-rs checks the Origin header 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, and allowed_origins adds origins. See Security
  • ๐Ÿ“ Audit Log Location: The audit log is now written next to the logs, to %USERPROFILE%\.mcp-rs\audit\audit.log on Windows, and on Linux and macOS it is readable by your user only. The old audit.log next 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 continued line with its pid and instance at the top
  • ๐Ÿ”Ž Which Process Did It: Each audit log record has pid and instance in metadata, matching the logโ€™s header lines and the Instance line of mcp_rs_status, so you can tell the two processes Claude Desktop starts apart
  • ๐Ÿ”’ Dependencies: jsonwebtoken 11.1 with the aws_lc_rs backend, 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\logs is no longer reported as a fallback

โœ… v0.19.2

  • ๐Ÿฉบ Status Tool: Ask your AI client to call mcp_rs_status to 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 --config without a path, so a typo does not silently use another config file

โœ… v0.19.1

  • ๐Ÿท๏ธ Version and Help: mcp-rs --version prints the installed version, and mcp-rs --help lists 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, and structuredContent are 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_media can read a file from folders allowed in upload_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-credentials generates the encrypted_credentials section
  • ๐Ÿ”Œ MCP Protocol Fixes: STDIO and HTTP no longer answer JSON-RPC notifications
  • ๐Ÿ—‘๏ธ Media Deletion Fix: delete_media with force: true no 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 audit now runs daily

See the Security documentation for details.

For older versions, see the CHANGELOG and the releases.