How do I use tic-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., "@tic-mcp What tasks are on my shopping list?" 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.

tic-mcp

by charith-heymilo

Overview Schema Source Related Servers Discussions Admin

Python

Local

tic-mcp

An unofficial MCP server for Tic, the free floating sticky-note task app for macOS.

It lets an AI assistant read your Tic lists. You can ask "what is on my list?" and get an answer. You can also paste a screenshot onto a task and ask the assistant to look at it.

This project is not made by the Tic developer and is not connected to them. Tic's own source code is at kasvith/tic. Tested against Tic 0.4.0.

What it can do

Tool	What it does
`tic_lists`	Shows every list, and how many tasks are open or done
`tic_read`	Shows the tasks on one list
`tic_search`	Finds tasks by their text
`tic_image`	Shows the image attached to a task

You name a list or a task by part of its text. Capital letters do not matter.

Related MCP server: DB Insights MCP Server

It only reads

The server never writes to your notes. Every connection opens the database in read-only mode, so it cannot change your data even if there is a bug.

This is on purpose. See Why it does not write.

Install

You need macOS, Tic, and uv.

git clone https://github.com/charith-heymilo/tic-mcp.git
cd tic-mcp
uv sync

Add it to Claude Code:

claude mcp add -s user tic -- "$PWD/.venv/bin/python" -m tic_mcp.server

Then restart Claude Code. The tools show up after a restart.

To run the tests:

uv run pytest

The server reads ~/Library/Application Support/Tic/tic.sqlite by default. Set TIC_DB to point it somewhere else.

How Tic stores notes

Tic uses SQLite through GRDB. There are three tables.

Table	What it holds
`note`	One list, plus the position of its window
`task`	One line item. `indentLevel` sets how deep it is nested
`taskImage`	An optional PNG for a task, kept in the database

Some details are easy to get wrong:

IDs are 16-byte blobs, not text. Each one is a UUID.
Times are UTC, but no time zone is stored. They look like local time. If you read them as local time, every value is off by your own offset.
sortIndex has no gaps. It runs 0, 1, 2 and so on. To insert a task you must renumber the ones after it.
Foreign keys are off by default, so ON DELETE CASCADE does not run unless you turn them on.
Tic uses journal_mode=delete, so a writer locks the whole file.

Images

Tic stores plain PNG files, so a screenshot you paste onto a task reads back as-is.

Big images are made smaller first. The longest edge is capped at 1568 pixels. Claude reduces images to that size anyway, so no detail is lost and large screenshots do not waste tokens.

Resizing uses sips, which comes with macOS. This keeps the project free of an image library.

The crop box is reported, not applied. Tic saves a crop box for every image. Applying it needs a real image library, so the server sends the whole image and tells you when a crop exists. You see all of the screenshot, which is usually what you want.

Why it does not write

Tic has no API. There is no URL scheme, no AppleScript support, and no command line tool. The SQLite file is the only way in.

Writing is possible, but it works badly. What follows was measured, not guessed.

Tic does not see writes from other programs. Tic watches its database with GRDB, which only reports changes that Tic itself makes. A task added from outside stays hidden until Tic writes to the same table for its own reasons:

What you do in Tic	Does the outside task appear?
Open the list	No
Change the list title	No
Add a line item	Yes

Writes from outside are not lost, though. Tic updates one record at a time. It does not rewrite a whole list. It also reads the database when it picks the next sortIndex. So a task added from outside stays where it is, and the order stays correct.

Restarting Tic loses your window layout. Tic decides where to put each window when it starts, then saves those new positions over the old ones. The notes open stacked on top of each other, and the old positions are gone. Writing the old positions back does not help, because the next start overwrites them again.

This rules out the obvious plan of "quit Tic, write, then start it again". It would cost you your window layout every time.

If writing is added later, the better way is to write while Tic runs, and tell the user that the change shows up when they next touch that list.

Files

tic_mcp/db.py       Read-only queries. Decodes UUIDs and UTC times
tic_mcp/images.py   Reads PNG sizes, and makes images smaller
tic_mcp/server.py   The four tools, and how their output is written
tests/              119 tests, including real stdio round trips

db.py returns data. server.py does all the formatting.

The server also checks Tic's list of migrations. If Tic adds one this code does not know about, the tool output says so. You get a warning instead of wrong data.

License

MIT

Available Tools

4 tools

tic_imageA

Read-only

View the image or screenshot attached to a Tic task. Identify the task by its text (partial, case-insensitive). Tasks that have an image are marked [img] in tic_read and tic_search output.

ParametersJSON Schema

Name	Required	Description	Default
`task`	Yes

TDQS

A4.2/5.0

Behavior3/5

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

The annotations already declare readOnlyHint=true, so the safe-read behavior is covered. The description adds useful behavioral details like partial, case-insensitive task text matching and the [img] marker convention, but it does not disclose behavior for ambiguous matches, missing images, or error cases.

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 sentences carry the entire needed meaning with no filler. The primary action is front-loaded, and the important [img] marker guidance is included efficiently.

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

Completeness4/5

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

For a simple read-only tool with one parameter and no output schema, the description covers what it does, how to identify the target task, and when it applies via the [img] marker. It is slightly incomplete in that it does not address ambiguous partial matches or the exact form of the returned image, but these are minor for this low-complexity tool.

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

Parameters4/5

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

The schema provides no description for the 'task' parameter (0% coverage), so the description must compensate. It does by explaining that the task is identified by its text and that matching is partial and case-insensitive, giving the agent meaningful guidance beyond the bare schema.

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 opens with a specific verb and resource: 'View the image or screenshot attached to a Tic task.' It clearly distinguishes this tool from its siblings (tic_read, tic_search, tic_lists) by focusing on image retrieval, and adds how the task is identified via partial text.

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

Usage Guidelines4/5

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

The description gives clear context for when to use this tool: tasks with an image are marked '[img]' in tic_read and tic_search output, so an agent knows to call tic_image only for tasks carrying that marker. It references the sibling tools that produce the marker, though it does not explicitly state when not to use it.

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

tic_listsA

Read-only

List every Tic note with how many tasks are open and completed. Use this to discover what lists exist before reading one.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the agent knows this is a safe, closed-world read. The description adds useful output details (every Tic note with open/completed task counts) but does not go beyond that to disclose potential limitations, pagination behavior, or edge cases. Given the annotation coverage, this aligns with the calibration bar for a read-only list tool.

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 sentences, each earning its place: the first states the operational behavior, the second provides usage timing. The core action 'List every Tic note' is front-loaded. No filler or redundancy.

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?

For a parameterless tool with a closed-world read-only annotation and an output schema present, the description is complete. It tells the agent what it returns (every list with counts) and when to invoke it. The output schema can carry any additional return-field details, so no further prose is needed.

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

Parameters4/5

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

The tool has zero parameters and the schema shows no properties. Per the rubric, 0 parameters earns a baseline of 4. The description adds no parameter-specific information, which is appropriate because there is nothing to document.

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 states a specific verb-resource pair: 'List every Tic note' with the additional detail 'with how many tasks are open and completed.' This clearly distinguishes it from sibling tools like tic_read (reading a specific note) and tic_search (searching). An agent knows exactly what this tool produces.

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

Usage Guidelines4/5

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

The phrase 'Use this to discover what lists exist before reading one' gives clear contextual guidance for when to call this tool – as a precursor to reading a specific note. It does not explicitly name the alternative sibling (tic_read) or state exclusion conditions, but the intent is unambiguous for a list-first workflow.

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

tic_readA

Read-only

Read the tasks on one Tic note. Identify the note by title (partial, case-insensitive) or by id prefix. Open tasks only unless include_done is true. Subtasks are shown indented.

ParametersJSON Schema

Name	Required	Description	Default
`note`	Yes
`limit`	No
`include_done`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the readOnlyHint, it discloses non-obvious behavior: partial case-insensitive title matching, ID-prefix matching, open-tasks-only filtering unless include_done is true, and indented subtask display. There is no contradiction with annotations.

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?

Four short sentences, each carrying useful information, with the core action front-loaded. There is no filler, redundancy, or unnecessary detail.

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

Completeness4/5

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

The description covers identification, default filtering, and output formatting, and an output schema exists for return details. The missing limit semantics and lack of explicit sibling routing prevent a perfect score.

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

Parameters4/5

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

With 0% schema description coverage, the description compensates well for the required 'note' parameter and the 'include_done' default behavior. However, the 'limit' parameter is not explained, leaving a notable gap.

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 uses a specific verb and resource: 'Read the tasks on one Tic note.' It also specifies how to identify the note by title or ID prefix, which clearly separates it from sibling tools like tic_lists and tic_search.

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

Usage Guidelines4/5

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

The intended use is clear: read tasks from a single Tic note. It does not explicitly name alternatives or state when not to use the tool, so it falls short of full routing guidance.

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

tic_searchA

Read-only

Search Tic for tasks whose text contains the given term, across every note. Also reports notes whose title matches. Case-insensitive.

ParametersJSON Schema

Name	Required	Description	Default
`term`	Yes
`limit`	No
`include_done`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior4/5

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

The readOnlyHint annotation already covers the safety profile, and the description adds useful behavioral context: searching across every note, matching both task text and note titles, and being case-insensitive. The output schema covers return-value details, so no contradiction or missing critical behavior.

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 focused sentences deliver the main function, the scope, an additional matching mode, and a behavioral nuance. There is no filler or redundant restatement of the tool name.

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

Completeness4/5

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

For a read-only search tool with an output schema and a clear parameter list, the description is largely complete. It explains what is searched, how matching works, and notes title matching. The only notable gap is the meaning of limit and include_done, though their names and defaults make their basic intent reasonably inferable.

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

Parameters3/5

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

Schema description coverage is 0%, so the description must compensate. It clarifies the core 'term' parameter by saying it matches task text and note titles case-insensitively. However, 'limit' and 'include_done' are left entirely to the schema defaults and parameter names, which is a clear gap.

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?

States a specific verb ('Search') and a specific resource ('Tic tasks across every note') and adds a second behavior: matching note titles. It also includes the case-insensitive detail, which makes the tool's purpose clear and distinguishable from siblings like tic_read or tic_lists.

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

Usage Guidelines4/5

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

The description clearly implies when to use the tool: when looking for tasks or notes by textual content. It does not explicitly state when not to use it or point to a specific alternative, leaving some room for the agent to infer the boundary against sibling tools.

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.

4 tool updatesv0.1.0Sep 24, 2026
- First observedtic_image
- First observedtic_lists
- First observedtic_read
- First observedtic_search

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

A4.1/5.0

Scored 2026-09-24 19:00 across 4 tools

Disambiguation4/5

The tools are mostly distinct: listing notes, reading tasks, searching tasks, and viewing images are clear operations. However, tic_read and tic_search both return task text and can be confused when an agent wants to find a specific task, though their purposes (read one note vs. search across all) are distinct.

Naming Consistency4/5

All tool names use the prefix 'tic_' followed by a clear verb (list, read, search, image). The pattern is consistent, though 'tic_image' is slightly less descriptive than 'view_image' or 'get_image', but it still fits the verb_noun pattern.

Tool Count4/5

With 4 tools, the count is slightly low for a note-taking app that likely needs creation, update, and deletion. However, it's a reasonable scope for a read-only or retrieval-focused server, and each tool serves a distinct purpose.

Completeness2/5

The tools cover listing, reading, searching, and viewing images, but there are no tools to create, update, mark complete, or delete tasks or notes. This leaves the lifecycle incomplete, preventing agents from making any changes, which is a significant gap for a task management domain.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

HAVNOAuth
app.havnre
Read-only AI access to HAVN properties, leads, tasks, files, media, and analytics.
Real Estate CRM
2
OsboonOAuth
com.osboon
Read-only AI access to Osboon business card analytics, viewers, links, connections and contacts.
CRM Customer Data Platforms
1
OpenOakOAuth
org.openoak
Secure AI access to OpenOak tasks, notes, and Kanban boards.
Project Management Note Taking Workplace & Productivity
1
QueryBearOAuth
io.github.spencerpauly
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Databases RAG Systems
2

Related MCP Servers

safe-sql-mcp
Databases Developer Tools
ahmedabdirahman1-max
F
license
Not graded
quality
D
maintenance
Enables read-only SQL database access for AI assistants, allowing schema exploration and safe query execution without risk of data modification.
Updated 3 months ago (2026-06-14 18:23 UTC)
-
DB Insights MCP Server
Databases Developer Tools
six-eyes-dev
F
license
Not graded
quality
D
maintenance
Enables AI assistants to query SQL databases safely with read-only access, allowing schema discovery and SELECT queries while blocking writes and DDL operations.
Updated 3 months ago (2026-06-17 13:19 UTC)
-
DB MCP Gateway
Databases RAG Systems Search
mdadul
A
license
Not graded
quality
B
maintenance
Provides read-only access to databases for MCP-compatible AI tools, allowing schema exploration and SELECT queries without exposing credentials or risking data changes.
Updated a month ago (2026-08-25 17:17 UTC)
64 npm
3
MIT
shop-mcp
Databases
stalexsm
F
license
A
quality
C
maintenance
Enables AI agents to safely explore and query a SQLite database in read-only mode, allowing them to inspect schema and run analytical SQL queries without risking data modification.
Updated a month ago (2026-08-23 15:32 UTC)
3
-