MCP CopyQ Server

MCP- CopyQ ( ) LLM-.

CopyQ

mcp/
 info/        #    ( )
 /     #    ( )
 workspace/   #   + 

(Item)

:

• text
• tags ( )
• note

---

(3 .)

1. mcp_read

.

		Default
mode	"tree" / "list" / "item" / "search"		****
tab	string	""	: "info", "workspace/proj1"
index	number		mode=item
query	string		mode=search (regex)
search_in	"text" / "note" / "tags" / "all"	"all"
max_depth	number	2	tree .
max_items	number	20
skip	number	0	N
include_text	bool	true	/
include_tags	bool	true
include_note	bool	false

(mode)

tree

mcp/info [5]
  0: "  API..." [api,docs]
  1: " ..." [config]
mcp/workspace [3]
   mcp/workspace/1 [12]

list

mode:list|tab:info|total:47|showing:0-19
0|"  API..."|[api,docs]|+note
1|" ..."|[config]|

item

search

TAB_NOT_FOUND
INDEX_OUT_OF_BOUNDS
INVALID_MODE	mode

(CopyQ CLI)

# tree
copyq tab | grep "^mcp/"
copyq tab "mcp/..." count
copyq tab "mcp/..." read 0 | head -c 50

# list
copyq tab "mcp/${tab}" count
copyq tab "mcp/${tab}" read $i
copyq tab "mcp/${tab}" read "application/x-copyq-tags" $i

# item
copyq tab "mcp/${tab}" read ${index}
copyq tab "mcp/${tab}" read "application/x-copyq-tags" ${index}
copyq tab "mcp/${tab}" read "application/x-copyq-item-notes" ${index}

# search
copyq eval "/* JS: grep  tabs */"

---

2. mcp_write

.

		Default
mode	string		**** (. )
tab	string
index	number		item-
text	string		( add/update)
tags	string[]
note	string
field	"text" / "note" / "tags"		update
edit_mode	"replace" / "append" / "prepend" / "substitute"	"replace"
match	string		substitute
to_tab	string		move
path	string		tab_create/tab_delete
intent	"execute" / "preview"	"execute"

(mode)

mode
add	item		tab, text
update	item		tab, index, field, (text/tags/note)
delete	item		tab, index
move	item		tab, index, to_tab
tab_create	collection		path ( workspace/*)
tab_delete	collection		path ( workspace/*)

edit_mode update

field	edit_mode
text/note	replace
text/note	append
text/note	prepend
text/note	substitute	match text/note
tags	replace
tags	append	( )
tags	remove

intent: preview

intent="preview" , :

action: delete
target: mcp/info[3]
will_remove: "  ..." | [] | +note

TAB_NOT_FOUND
INDEX_OUT_OF_BOUNDS
PERMISSION_DENIED	tab_create/tab_delete workspace
INVALID_MODE	mode
MISSING_PARAM
MATCH_NOT_FOUND	substitute: match

ok|mode:add|tab:info|index:0|text_len:156|tags:2

(CopyQ CLI)

# add
copyq tab "mcp/${tab}" write 0 \
  "text/plain" "${text}" \
  "application/x-copyq-tags" "${tags}" \
  "application/x-copyq-item-notes" "${note}"

# update (substitute)
OLD=$(copyq tab "mcp/${tab}" read ${index})
NEW=$(echo "$OLD" | sed "s/${match}/${value}/g")
TAGS=$(copyq tab "mcp/${tab}" read "application/x-copyq-tags" ${index})
NOTE=$(copyq tab "mcp/${tab}" read "application/x-copyq-item-notes" ${index})
copyq tab "mcp/${tab}" write ${index} \
  "text/plain" "$NEW" \
  "application/x-copyq-tags" "$TAGS" \
  "application/x-copyq-item-notes" "$NOTE"

# delete
copyq tab "mcp/${tab}" remove ${index}

# move
# read all  write to to_tab  remove from tab

# tab_create
copyq tab "mcp/${path}"

# tab_delete
copyq removeTab "mcp/${path}"

---

3. mcp_validate

.

tool	"read" / "write"
params	object

:

valid: true | warnings: [] | estimated_tokens: 340

:

valid: false | errors: ["TAB_NOT_FOUND: workspace/xxx"]

---

	info		workspace
read ( )
add
update
delete
move
tab_create
tab_delete

---

# 
# - Python 3.11+
# - CopyQ   
# -   CopyQ: C:\Program Files\CopyQ\copyq.exe

# 
cd C:\sts\projects\mcp-copyq
uv venv
uv pip install -e .

# 
uv run mcp-copyq

Claude Desktop

{
  "mcpServers": {
    "copyq": {
      "command": "uv",
      "args": ["--directory", "C:\\sts\\projects\\mcp-copyq", "run", "mcp-copyq"]
    }
  }
}

---

mcp_read(mode="tree", max_depth=2, max_items=5)

mcp_read(mode="list", tab="info", max_items=10, include_note=true)

mcp_read(mode="item", tab="info", index=0)

mcp_read(mode="search", query="API", search_in="all", max_items=10)

mcp_write(mode="add", tab="info", text=" ", tags=["important"])

( )

mcp_write(mode="update", tab="info", index=0, field="text", edit_mode="append", text="\n\n")

mcp_write(mode="update", tab="info", index=0, field="text", edit_mode="substitute", match="", text="")

( )

mcp_write(mode="update", tab="info", index=0, field="tags", edit_mode="append", tags=["urgent"])

mcp_write(mode="delete", tab="info", index=0, intent="preview")
mcp_write(mode="delete", tab="info", index=0, intent="execute")

mcp_write(mode="tab_create", path="workspace/_")

mcp_write(mode="move", tab="info", index=0, to_tab="workspace/")

---

1. ** ** 3 10+
2. Stateless
3. ** ** pipe-separated,
4. **** skip/max_items
5. ** ** include_text fields: "minimal"
6. Preview mode intent="preview"
7. ** ** +

---

mcp-copyq/
 README.md
 pyproject.toml
 src/
    mcp_copyq/
        __init__.py
        server.py          # MCP server
        copyq_client.py    # CopyQ CLI wrapper
        tools/
           __init__.py
           read.py        # mcp_read
           write.py       # mcp_write
           validate.py    # mcp_validate
        models.py          # Pydantic models
        errors.py          # Error codes
 tests/
     __init__.py
     test_read.py
     test_write.py
     test_validate.py
     test_integration.py

---

MIT