Junk Drawer MCP Server

A local MCP server cataloguing the small things that vanish: cables, adapters, batteries, craft bits, spare keys. You add an item once - with a location note, tags and a photo hint - and after that the question "do we have an HDMI adapter?" takes one tool call instead of twenty minutes of opening drawers.

Distinct from:

• gear-serial-inventory-webapp - that one is for serial-numbered gear; this one is for unlabeled small things.

• free-home-inventory-kit - that one is for insurance paperwork and printables; this one is for daily "where is it" moments.

By Asdale Dynamics, LLC - AI explained like a friend would: plain English, step by step, never condescending.

What it does

• add_item - catalogue a thing: name, kind (cable, adapter, battery, craft, key, hardware, office, medical, media, other), room, container note, description, tags, photo hint.

• search - ask in plain words: "do we have an HDMI adapter", "spare house key", "AA batteries". Scoring leans on name and tags; small plural/singular differences are forgiven.

• where_is - one item's full story: exact spot, photo hint, move log.

• list_by_room - items in one room, or (with no room) counts per room.

• mark_moved - record a relocation; keeps the record and reality agreeing, which is the whole point.

• move_history - every recorded hop for an item.

• remove_item - mark something gone (used up, given away, binned).

• summary - calm overview: counts by kind, moves on file.

• list_kinds - the kinds the drawer knows.

• Prompt: find_my_thing - a gentle walk through a lost-thing question.

No personal data needed, nothing leaves your machine, and photos are not required either: the photo_hint field just tells future-you what to snap (e.g. "silver coil left of the tape measure") so you can verify at a glance.

Related MCP server: inventory-mcp

Quick start

pip install -e .
export JUNK_DRAWER_DB=$PWD/data/drawer.json   # optional, this is the default spot
junk-drawer-server                            # talks MCP over stdio

Or run as a module: python -m junk_drawer.server.

Point your MCP client at it

{
  "mcpServers": {
    "junk-drawer": {
      "command": "junk-drawer-server",
      "env": { "JUNK_DRAWER_DB": "/home/you/junkdrawer/drawer.json" }
    }
  }
}

Storage

• Default: plain JSON at data/drawer.json (override with JUNK_DRAWER_DB).

• SQLite: give JUNK_DRAWER_DB a path ending in .db, .sqlite or .sqlite3 and the server uses a single-table SQLite file instead. Same tools, same behaviour.

Both files are the entire state of the system: copy one and you have a backup.

Examples

add_item "HDMI to mini HDMI adapter" kind=adapter room="office" \
         container="tin, second drawer down" tags="hdmi, video" \
         photo_hint="coiled grey cable left of the tape measure"
search "do we have an HDMI adapter"
list_by_room "office"
mark_moved "hdmi-to-mini-hdmi-adapter" new_room="lounge" \
           new_container="TV cabinet, cable pouch" note="wiring the new telly"

Development

pip install -e .
pip install pytest
python -m pytest          # 60+ tests, all local

License

MIT - Copyright (c) 2026 Asdale Dynamics, LLC. See LICENSE.