tisket MCP server
Commit Nov 9, 2026Lets an AI client manage a git-tracked, file-based issue tracker using markdown files and YAML frontmatter.
Also known as cjohnhanson/tisket
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 9, 2026
- License
- MIT
What is tisket MCP?
tisket lets an AI client manage a git-tracked, file-based issue tracker using markdown files and YAML frontmatter.
Summary generated from the project's README
About tisket MCP server
Tisket provides a way for coding agents to manage issues using markdown files and YAML frontmatter stored directly within a git repository. Instead of relying on external services or API tokens, this tool operates locally and works offline by treating issues as ordinary files inside a .tisket directory. This approach allows developers to keep their task tracking version-controlled alongside their code.
Users can interact with the tracker through a command line interface or by running a server via the tisket serve command to connect with a Model Context Protocol client. The server is read-only by default, but can be configured with the --access read-write flag to allow an agent to append information to scratch notes. It does not require authentication, so it is recommended to bind it to localhost or use a proxy.
The system tracks an issue lifecycle through statuses like discovery, todo, in_progress, and done. It also features git-aware divergence detection, which identifies if an issue has different metadata on other branches by comparing files field by field.
What you can do with it
- 1List open tasksAn AI agent can retrieve a list of all current issues to understand the project backlog.
- 2Record investigation findingsA developer can instruct an agent to append technical logs or failed approaches to an issue's scratch notes section.
- 3Search for specific topicsYou can ask an AI to find all issues related to a specific technical subject using regular expressions.
- 4Detect branch discrepanciesAn agent can check if the status or priority of an issue differs across various git branches.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecjohnhanson/tisket is public and reachablegithub.com/cjohnhanson/tisket ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/cjohnhanson/tisket ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubtisket
A plaintext, git-tracked issue tracker. Each issue is a markdown file
with YAML frontmatter. The files live in .tisket/ inside your git
repo. Tisket needs no external service and no API tokens. It works
offline. Coding agents read and write issues as ordinary file
operations instead of calls to a hosted API.
Install
The command is tisket, whichever package you install.
Archives of precompiled binaries are available for macOS and Linux. The Linux binaries are static executables. Each archive holds the binary, its man pages, the README and the licence. There is no Windows build.
| Package manager | Package | Command |
|---|---|---|
| Homebrew | cjohnhanson/tap/tisket | brew install cjohnhanson/tap/tisket |
| Cargo | tisket | cargo install --locked tisket |
| uv | tisket | uv tool install tisket |
| npm | tisket | npm install -g tisket |
On Debian or Ubuntu, download the .deb from the releases
page and install it:
wget https://github.com/cjohnhanson/tisket/releases/download/v0.2.6/tisket_0.2.6-1_amd64.deb
sudo dpkg -i tisket_0.2.6-1_amd64.deb
To run it once without installing anything:
uvx tisket issue list
npx tisket issue list
Building
tisket is written in Rust, so you need a Rust
installation to compile it. tisket compiles
with Rust 1.88 or newer. A C compiler is needed as well, which
aws-lc-sys uses for its cryptography.
To build tisket:
git clone https://github.com/cjohnhanson/tisket
cd tisket
cargo build --release
./target/release/tisket --version
Usage
Follow Getting started with tisket to define a task, save a checkpoint, and finish from another terminal.
tisket init # create tracker and project configuration
tisket issue create "Fix the thing" # create an issue
tisket issue list # list open issues
tisket issue list -s todo # filter by status
tisket issue show ab12 # show the issue details
tisket issue edit ab12 --add-label urgent
tisket issue close ab12 # move the file to .closed/
tisket search "TLS|certificates" # search every issue with a regex
tisket store list # show this tracker and the trackers it declares
tisket serve [--bind ADDR] # serve this tracker over MCP
tisket docs [topic] # show the bundled documentation
How it works
Each issue is one file. The filename has a 4-character random prefix
and a slug from the title. The file holds YAML frontmatter for the
metadata and a markdown body. Tisket moves a closed issue to
.closed/.
.tisket/
default/ # project directory
ab12-fix-the-widget.md # open issue
.closed/
cd34-old-resolved-thing.md # closed issue
An issue moves through a status lifecycle: discovery → todo →
in_progress → done (or cancelled). An issue can also be blocked
or paused.
Scratch notes
Each issue can have a ## Scratch Notes section below the issue body.
An agent appends its working notes there: investigation logs,
approaches that failed, and partial findings. The problem description
above stays unchanged.
tisket scratch ab12 append "Confirmed: bounds check missing on line 42"
tisket scratch ab12 read
Git-aware divergence detection
When you list or show an issue, tisket also reads that issue file from
every other branch. It compares the files field by field. If another
branch has a different status, assignee, or priority, tisket marks the
issue with a *. It also names each branch that differs. tisket does
not compare an open issue with its closed copy on another branch.
Serving over MCP
tisket serve offers the same tracker to a Model Context Protocol
client. The library answers both interfaces, so the server returns what
the CLI returns.
tisket serve # speak MCP on stdin and stdout
tisket serve --bind 127.0.0.1:7432 # serve over HTTP at /mcp on that address
tisket serve --access read-write # also allow appending to working notes
The server is read-only by default. With --access read-write it adds
one write: appending to an issue's scratch notes. A caller cannot
create an issue, change a status, or edit a body through the server. A
served tracker has no authentication: bind it to 127.0.0.1, or put a
proxy that authenticates in front of it.
Documentation
- What is Tisket? — design, file format, status lifecycle
- Getting Started — first issue walkthrough
- Workflow — daily issue management past the basics
- How to organize dependencies and epics
- How to reconcile issue state across worktrees
- File format — every field of an issue file
- CLI Reference — complete command documentation
tisket docs prints the same pages from the installed binary.
Related
Tisket belongs to a group of plaintext, git-tracked, agent-readable tools.
- zettel — zettelkasten notes for a repository
- almanac — agent skill index, over pluggable sources
- gaff — context-lifecycle handler for coding agents
- missouri — end-to-end tests as directed graphs of filesystem states
- mdstore — the frontmattered markdown library tisket stores issues with
License
MIT.
tisket MCP questions
How does tisket store issues?
Issues are stored as individual markdown files with YAML frontmatter inside a .tisket/ directory within your git repository.
Can I use tisket with an AI agent?
Yes, coding agents can read and write issues as ordinary file operations, and you can serve the tracker over MCP for direct integration.
Does the MCP server support writing data?
By default, the server is read-only, but using the --access read-write flag allows the agent to append to an issue's scratch notes.
Is authentication required for the MCP server?
A served tracker has no built-in authentication; it is recommended to bind it to localhost or use an authentication proxy.