Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@espanso-mcp Create a text expansion :sig for my email signature"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server for managing Espanso text expansion configurations. This server allows AI assistants like Claude to interact with your Espanso setup, making it easy to create, update, and manage text expansions.
Espanso Resources:
List all match files and expansions
Create new text expansions with simple or complex patterns
Update existing expansions
Delete expansions you no longer need
Templates for common expansion patterns
Cross-platform support (Linux, macOS, Windows)
Related MCP server: Snippet Saver
Clone this repository:
git clone https://github.com/bkaes/espanso-mcp.git
cd espanso-mcpInstall dependencies and build:
npm install
npm run buildAdd to your MCP configuration:
{
"mcpServers": {
"espanso": {
"command": "node",
"args": ["/absolute/path/to/espanso-mcp/dist/index.js"]
}
}
}Note: The configuration file location varies by platform:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json
Once configured, you can ask Claude to:
"Show me all my Espanso text expansions"
"Create an Espanso expansion that types my email signature when I type :sig"
"Add an expansion :today that inserts today's date in YYYY-MM-DD format"
"Change the :sig expansion to include my phone number"
"Remove the :old expansion from my Espanso config"
list_match_files - List all YAML files containing expansions
list_matches - Show all expansions (optionally filtered by file)
create_match - Add a new text expansion
update_match - Modify an existing expansion
delete_match - Remove an expansion
get_config_info - Display Espanso configuration details
generate_documentation - Generate markdown documentation for your expansions
The MCP server can generate comprehensive documentation for your Espanso shortcuts:
"Create documentation for all my Espanso shortcuts"
"Document just my email expansions"
Documentation is saved in your Espanso config directory under docs/ by default, making it easy to:
Keep documentation with your expansions
Reference from project READMEs
Share with team members
The server provides templates for common expansion patterns:
Simple text expansion - Basic trigger → replacement
Date expansion - Dynamic date insertion with custom formats
Form expansion - Interactive forms with user input
Node.js 18 or higher
Espanso installed and configured
Run the server in development mode:
npm run devThe codebase is organized into modular components:
src/index.ts - Entry point
src/server.ts - MCP server implementation
src/types/ - TypeScript interfaces
src/handlers/ - Business logic for each operation
src/utils/ - Utility functions
See CLAUDE.md for detailed architecture and design decisions.
GPL-3.0
Create a new text expansion
Inputs: replace (required), trigger (required), file, vars.
Delete a text expansion
Inputs: file (required), trigger (required).
Generate documentation for Espanso commands in a specific file or all files
Inputs: file, output_path.
Get Espanso configuration information
Inputs: no named parameters.
List all text expansions from a specific file or all files
Inputs: file.
List all Espanso match files
Inputs: no named parameters.
Update an existing text expansion
Inputs: file (required), trigger (required), newReplace, newTrigger.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 7 tools
Each tool targets a distinct resource or action: listing files vs. listing expansions vs. CRUD on expansions vs. config info vs. documentation generation. There is no meaningful overlap that would cause an agent to misselect among these tools.
All tool names use snake_case with a clear verb-first pattern: generate_documentation, list_match_files, list_matches, create_match, update_match, delete_match, get_config_info. The convention is consistent throughout.
Seven tools is well-scoped for Espanso match and configuration management. Each tool covers a distinct operation, and the count stays within a comfortable range without bloat.
Core match lifecycle is covered with create, update, delete, and list operations, plus file listing, config info, and documentation. Minor gaps exist around match-file management (create/delete/rename) and configuration mutation or reload operations.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
