How do I use macos-clipboard-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@macos-clipboard-mcp Paste the current clipboard content." 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.

macos-clipboard-mcp

by xiaoquisme

Overview Schema Source Related Servers Discussions Admin

Python

Local

MacOS Clipboard MCP

A simple utility that provides model context protocol (MCP) tools for interacting with the macOS clipboard.

Features

Copy text to the clipboard
Paste text from the clipboard
Paste images from the clipboard (supports TIFF, PNG, and JPEG formats)

Related MCP server: mcp-clipboard

mcp config

method1(recommended)

{
    "clipboard": {
        "command": "uvx",
        "args": [
            "macos-clipboard-mcp"
        ]
    }
}

method2

{
    "clipboard": {
            "command": "uv",
            "args": [
                "--directory",
                "<your-local-folder>/macos-clipboard-mcp",
                "run",
                "main.py"
            ]
        }
}

Installation

uv sync
python main.py

Requirements

Python 3.12+
macOS (uses AppleScript for clipboard operations)

Usage

Start the MCP server:

mcp dev main.py

This exposes the following MCP tools:

copy_to_clipboard(data: str): Copies text to the clipboard
paste_from_clipboard(): Returns text from the clipboard
paste_image_from_clipboard(): Returns images from the clipboard as base64-encoded PNG

Development

This project uses modern Python tooling:

uv for dependency management

License

MIT

Available Tools

3 tools

copy_to_clipboardC

copy data to clipboard

ParametersJSON Schema

Name	Required	Description	Default
`data`	Yes

TDQS

C2.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description bears full responsibility for disclosing behavioral traits. It does not mention that clipboard content will be overwritten or any permission requirements, which are critical for a clipboard-modifying tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence, which is concise but at the expense of important details. It is not verbose, yet leaves gaps that could be filled without significant length increase.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, the description should still cover key aspects like side effects (clipboard overwrite), compatibility (text only?), and any prerequisites. It fails to provide a complete picture, especially without annotations or output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has one parameter 'data' with no description and 0% schema description coverage. The description's phrase 'copy data to clipboard' adds only minimal context that the parameter is the content to copy, but does not clarify format, size limits, or type restrictions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'copy data to clipboard' clearly states the action and target resource. It implicitly distinguishes from sibling paste tools by specifying 'copy' rather than 'paste'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like paste_from_clipboard or paste_image_from_clipboard. The context signals show siblings exist, but the description offers no usage direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

paste_from_clipboardD

paste from clipboard

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

D1.3/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations and description provides no behavioral details (e.g., clipboard empty handling, permission requirements, or supported formats).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise but under-specified; the single phrase 'paste from clipboard' lacks essential information, making it insufficient rather than efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, no annotations, and description omits return values, side effects, or any operational context; completely inadequate for understanding the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters with 100% schema coverage; baseline is 4, but description adds no meaningful context beyond the tool name, failing to explain what the tool does.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description 'paste from clipboard' is a tautology, restating the name without specifying what is pasted (e.g., text) or distinguishing from sibling 'paste_image_from_clipboard'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives like 'copy_to_clipboard' or 'paste_image_from_clipboard'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

paste_image_from_clipboardA

Paste image from clipboard, automatically detect TIFF/PNG/JPEG formats, and always return the image as a PNG base64-encoded string. Returns an empty string if there is no image in the clipboard.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description effectively discloses key behaviors: auto-format detection, PNG conversion, and empty string on no image. However, it does not explicitly state if the operation is read-only or has side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences that front-load the purpose and key details, with no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, straightforward behavior), the description fully covers purpose, process, and return value, making it complete for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, and the description provides complete semantic context for the tool's behavior, meeting the baseline expectation for zero-parameter tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool pastes an image from the clipboard, automatically detects formats, and always returns as PNG base64. It distinguishes from sibling tools like paste_from_clipboard which likely handles text.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage for pasting images, but no explicit when-not or alternatives given. The sibling paste_from_clipboard suggests a distinction but not elaborated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv1.0.2Jun 9, 2026
- First observedcopy_to_clipboard
- First observedpaste_from_clipboard
- First observedpaste_image_from_clipboard

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3/5.0

Scored 2026-06-09 18:25 across 3 tools

Disambiguation5/5

Each tool targets a distinct clipboard operation: copying data, pasting text, and pasting images. No ambiguity between them.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case: copy_to_clipboard, paste_from_clipboard, paste_image_from_clipboard.

Tool Count5/5

Three tools are appropriate for a clipboard utility, covering the essential operations without bloat.

Completeness5/5

The tool set covers the fundamental clipboard actions: copy, paste text, and paste image. No obvious gaps for typical usage.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

shortcuts-bridgeOAuth
io.github.IsaiahDupree
MCP connector that lets ChatGPT list, search, and run your Apple Shortcuts via a local Mac agent
App Automation OS Automation
1
notesbridgeOAuth
io.github.IsaiahDupree
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Note Taking App Automation
1
Markdown A
io.github.pipeworx-io
Markdown utilities MCP.
Developer Tools File Systems
342
mission-controlOAuth
io.github.dinof777
Read and write Mission Control state via MCP — projects, tasks, subtasks, templates, status updates.
Project Management Workplace & Productivity
2

Related MCP Servers

MacOS Clipboard MCP Server
OS Automation App Automation
brian-ln
A
license
Not graded
quality
D
maintenance
Provides AI assistants access to the macOS clipboard content, supporting text, images, and binary data via OSAScript.
Updated 2 years ago (2025-03-08 11:22 UTC)
8
MIT
mcp-clipboard
Developer Tools OS Automation Workplace & Productivity
cmeans
A
license
A
quality
B
maintenance
MCP server that reads and writes the system clipboard — tables, text, code, JSON, URLs, images, and more. Preserves spreadsheet structure (rows/columns) that is lost when pasting into Claude directly.
Updated 2 months ago (2026-07-20 11:08 UTC)
4
24 PyPI
5
Apache 2.0
maus-mcp
Developer Tools Note Taking OS Automation
mnlt
A
license
Not graded
quality
D
maintenance
MCP server that gives AI agents access to your Maus clipboard on macOS, enabling them to write clean text into history, search, and manage clipboard items locally.
Updated 3 months ago (2026-06-24 12:08 UTC)
6 npm
MIT
AppleScript Automation MCP
OS Automation App Automation
anmolol117
A
license
A
quality
B
maintenance
A local MCP server that exposes macOS automation actions (AppleScript + CLIs) as tools, enabling MCP clients on your Mac to control apps, system settings, and more.
Updated 2 months ago (2026-07-21 10:03 UTC)
39
MIT