motivate-mcp

An MCP server that returns a motivational quote matched to the task you are actually working on.

Most quote generators pick at random, which is why they stop landing after a day. This one reads a short description of what you are doing, scores it against a keyword map, and returns something relevant. Say you are debugging and you get Kernighan. Say you are stuck and you get Mandela. Say you are avoiding shipping and you get told to ship.

> "When you have eliminated the impossible, whatever remains, however improbable,
>  must be the truth."
>     — Arthur Conan Doyle

72 quotes across 57 topics. No API key, no network calls, no telemetry.

Install

git clone https://github.com/lazyturtle22/motivate-mcp.git
cd motivate-mcp
npm install

Use it as an MCP server

Add it to your MCP client config. For Claude Code, ~/.claude.json:

{
  "mcpServers": {
    "motivate": {
      "command": "node",
      "args": ["/absolute/path/to/motivate-mcp/src/index.js"]
    }
  }
}

Restart the client and three tools appear.

Tools

Tool	What it does
motivate	Returns a quote matched to a task description. Takes task (string) and optional avoid_repeats (boolean, default true)
list_topics	Lists every topic and how many quotes sit under it
explain_match	Shows which topics a description matches, without returning a quote. Useful when tuning the keyword map

Repeats are tracked per session, so a long session will not serve you the same line twice until it runs out of relevant ones.

Getting a quote on every message

An MCP tool only fires when the model decides to call it, so it will not reliably hit every message. If you want one every time, use the included hook instead. It runs on every prompt you submit, reads what you typed, and prints a matched quote into the context.

Add to ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /absolute/path/to/motivate-mcp/hook/motivate-hook.js"
          }
        ]
      }
    ]
  }
}

Set MOTIVATE_QUIET=1 to silence it without unwiring it. The hook fails silently by design: a broken quote generator should never be able to break your prompt.

The two can run together. The hook gives you the every-message drip, the MCP tool lets the model ask for one deliberately when it thinks you need it.

How the matching works

src/match.js holds a map of topic to signal words. A task description is scanned for those words, topics are scored (multi-word phrases count double, since they are stronger evidence), and quotes are ranked by how well their topics overlap the top matches.

Signals match at a word start, not anywhere in the string. This matters if you add your own. A plain substring check looks fine until you notice ui fires on "built" and "guide", try fires on "country", and lead fires on "misleading" — so you ask about building something and get a quote about design.

There is deliberately no boundary on the end of a signal, so stems still work: optimis matches "optimising", frustrat matches "frustrated". When adding a short signal (three characters or fewer), check it against a few real sentences first.

The final pick is randomised across everything within 70% of the best score, so the same input does not always produce the same line.

If nothing matches, it falls back to the whole database rather than returning nothing.

Check what a description matches before adding new signal words:

node -e "import('./src/match.js').then(m => console.log(m.scoreTopics('your text here')))"

Adding quotes

Edit src/quotes.js. Each entry is:

{
  text: "The quote itself.",
  by: "Who said it",
  topics: ["debugging", "persistence"],
}

Attribution rules, please keep to them:

• Where a line is widely repeated but the original wording or source is disputed, by starts with attributed to. Do not strip that prefix to make it look tidier.
• Proverbs and genuinely anonymous lines are credited as Proverb or Anonymous.

Use topics that already exist where you can, so quotes cluster rather than scatter. Run npm test afterwards, which checks for duplicates, missing authors and orphan topics.

Tests

npm test

Nine tests using the built-in node:test runner. No framework, no build step.

Licence

MIT. See LICENSE.