espanso-mcp

Espanso MCP Server

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:

• 🌐 Espanso Website
• 📚 Espanso Documentation
• 💻 Espanso GitHub Repository

Features

• 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)

Installation

1. Clone this repository:

git clone https://github.com/bkaes/espanso-mcp.git
cd espanso-mcp

2. Install dependencies and build:

npm install
npm run build

3. Add 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

Usage

Once configured, you can ask Claude to:

List all expansions

"Show me all my Espanso text expansions"

Create a new expansion

"Create an Espanso expansion that types my email signature when I type :sig"

Create a date expansion

"Add an expansion :today that inserts today's date in YYYY-MM-DD format"

Update an expansion

"Change the :sig expansion to include my phone number"

Delete an expansion

"Remove the :old expansion from my Espanso config"

Available Tools

• 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

Documentation Generation

The MCP server can generate comprehensive documentation for your Espanso shortcuts:

Generate documentation for all expansions

"Create documentation for all my Espanso shortcuts"

Generate documentation for specific file

"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

Templates

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

Requirements

• Node.js 18 or higher
• Espanso installed and configured

Development

Run the server in development mode:

npm run dev

Project Structure

The 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

Contributing

See CLAUDE.md for detailed architecture and design decisions.

License

GPL-3.0