# Waymark

> Waymark is an open-source MCP server for developer tools. Query and edit Markdown work items, dependencies and trees in a Git repo. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, Linux, macOS, Windows
- **Repository:** https://github.com/qiyueran-source/waymark/tree/HEAD/waymark/crates/waymark-mcp
- **MCP Registry name:** io.github.QiYueran-source/waymark
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools), [productivity](https://ai-powered.com/categories/productivity)
- **Listing updated:** 2026-11-18

## About

Waymark keeps project work as Markdown files inside your Git repository, and this server lets an agent read and write that same project over stdio. There is no daemon, no database and no network access: the server finds the nearest .waymark/config.toml walking up from its start directory, or from a directory given with --project.

The tool set goes beyond create and list. Agents can fetch ready or blocked items, walk the parent tree or the dependency tree, set parents and soft links, transfer an owner, archive items, and edit configuration categories and custom fields. Diagnostic tools validate the project, run a doctor check, migrate version, schema or storage, and show git history and diffs.

Every success returns a versioned envelope with data and metadata; every business failure returns a stable error code, typed details and a retryable flag, so a client can tell a bad argument from a missing project or a concurrent edit. It is installed with cargo or from prebuilt Linux, macOS and Windows binaries, and is licensed MIT or Apache-2.0.

## Features

- **Ready and blocked views:** List items that can start now or are waiting on others.
- **Tree and dependencies:** Walk parent trees and dependency trees.
- **Full item editing:** Create, retitle, rebody, status, move and archive items.
- **Config management:** Add and change categories and custom fields.
- **Git history:** Read history and diffs for work items.
- **Structured errors:** Stable codes with a retryable flag.

## Good for

- Let an agent pick the next unblocked task
- Create and link work items from a planning chat
- Audit dependencies before starting a feature
- Validate a project's work-item files

## Install

### Claude Code (Terminal)

```sh
claude mcp add waymark -- npx -y waymark-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "waymark": {
      "command": "npx",
      "args": [
        "-y",
        "waymark-mcp"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "waymark": {
      "command": "npx",
      "args": [
        "-y",
        "waymark-mcp"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "waymark": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "waymark-mcp"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "waymark": {
      "command": "npx",
      "args": [
        "-y",
        "waymark-mcp"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "waymark": {
      "command": "npx",
      "args": [
        "-y",
        "waymark-mcp"
      ]
    }
  }
}
```

## Tools

- `waymark_project_info`: Show project information.
- `waymark_get_work_item`: Fetch one work item.
- `waymark_list_work_items`: List work items.
- `waymark_search_work_items`: Search work items.
- `waymark_get_stats`: Get project statistics.
- `waymark_get_tree`: Read the parent tree.
- `waymark_get_dependency_tree`: Read the dependency tree.
- `waymark_get_ready_items`: List items ready to start.
- `waymark_get_blocked_items`: List blocked items.
- `waymark_create_work_item`: Create a work item.
- `waymark_set_status`: Set an item's status.
- `waymark_add_dependency`: Add a dependency.
- `waymark_archive_work_item`: Archive an item.
- `waymark_validate`: Validate the project.
- `waymark_doctor`: Run diagnostics.
- `waymark_git_history`: Show git history.
- `waymark_git_diff`: Show a git diff.

## FAQ

### Does it need a server or database?

No. It reads and writes Markdown files in your repo with no daemon, database or network access.

### How do I install it?

cargo install waymark-mcp, or download a prebuilt binary from the releases page.

### How does it find the project?

It walks up to the nearest .waymark/config.toml, or starts at the --project directory.

### What licence?

MIT OR Apache-2.0.

### Is Waymark free?

Yes. Waymark is open source, so you can use and self-host it for free.

### How do I add Waymark to Claude Code?

Run this command in your terminal: claude mcp add waymark -- npx -y waymark-mcp

### What are the best alternatives to Waymark?

The closest alternatives to Waymark are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Context7](https://ai-powered.com/mcp/context7): Context7 is a freemium MCP server for developer tools.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [awesome-mcp-servers](https://ai-powered.com/mcp/awesome-mcp-servers-2): awesome-mcp-servers is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/waymark-2
