technical-notes-mcp

A Model Context Protocol server that lets Claude — or any MCP-compatible client — search your local notes directory and check live system resource usage. Built with TypeScript on the official @modelcontextprotocol/sdk, talking over stdio.

Demo

Related MCP server: File Search Tool

Architecture

The server is a Node process spoken to over stdio using JSON-RPC 2.0. Each MCP client (Inspector, Claude Desktop, Claude Code) spawns it as a subprocess and exchanges messages on its stdin/stdout. The server exposes two tools that read from the local filesystem and the Node os module.

Tools

search_technical_notes

Searches a local directory of markdown and code files for a keyword and returns the contents of the most relevant file.

Supported extensions: .md, .mdx, .txt, .ts, .tsx, .js, .jsx, .py, .go, .rs, .java, .c, .cpp, .h, .hpp, .rb, .sh, .json, .yaml, .yml. Files over 1 MB are skipped; node_modules, .git, dist, build, .venv, __pycache__, .cache, .next are pruned during the walk.

get_system_resource_usage

Returns a live snapshot of the host's CPU and memory.

This is more accurate than os.loadavg() (which is Unix-only) and works on every platform Node supports.

Quick start

Requirements

• Node.js 18 or later

• An MCP client — the MCP Inspector for testing, or Claude Code for daily use

Install and build

git clone https://github.com/poplores/technical-notes-mcp.git
cd technical-notes-mcp
npm install
npm run build

The build produces build/index.js — the entry point an MCP client will spawn.

Configure your notes directory

The search tool reads from NOTES_DIR. Set this in your MCP client config (examples below) — never hardcode it in the source.

Verify it works

Run the official Inspector against the build:

NOTES_DIR=/path/to/your/notes npm run inspector

Windows (Command Prompt):

set NOTES_DIR=C:\path\to\your\notes
npm run inspector

Open the URL the Inspector prints, click Connect, then the Tools tab. Both tools should appear. Run search_technical_notes with a keyword you know is in your notes — it should return the matching file. Run get_system_resource_usage twice in a row — the timestamp and uptime should change, confirming live data.

Use it with an MCP client

Claude Code (recommended)

claude mcp add technical-notes \
  --env NOTES_DIR=/absolute/path/to/your/notes \
  -- node /absolute/path/to/technical-notes-mcp/build/index.js

Then in any Claude Code session: "Search my technical notes for X" or "What's my CPU usage?"

Claude Desktop

⚠️ The current MSIX/Microsoft Store builds of Claude Desktop on Windows have a known bug where they silently ignore mcpServers in claude_desktop_config.json. The macOS build is unaffected. If you're on Windows, use Claude Code for now.

On macOS, edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "technical-notes": {
      "command": "node",
      "args": ["/absolute/path/to/technical-notes-mcp/build/index.js"],
      "env": {
        "NOTES_DIR": "/absolute/path/to/your/notes"
      }
    }
  }
}

Restart Claude Desktop fully.

Project structure

technical-notes-mcp/
├── src/
│   └── index.ts            # Server setup + both tool handlers
├── docs/
│   ├── architecture.svg    # Diagram embedded above
│   └── demo.gif            # Demo embedded above
├── .github/workflows/
│   └── build.yml           # CI: typecheck + build on Node 18/20/22
├── package.json            # ESM, bin entry, build/inspector scripts
├── tsconfig.json           # ES2022 / Node16 module resolution
├── LICENSE                 # MIT
└── README.md

How it works (under the hood)

This is a stdio MCP server: a Node process that reads JSON-RPC requests on stdin and writes responses on stdout. Each MCP client spawns it as a subprocess; there's no network, no port, no shared state.

Don't console.log from a stdio MCP server. stdout is reserved for the protocol. The server uses console.error (stderr) for its startup message. Any stray write to stdout will break the JSON-RPC stream.

The get_system_resource_usage tool samples CPU counters twice over 500 ms and computes the busy-time delta across all cores — see the getCpuUsagePercent function in src/index.ts if you want to tune the sample window.

The search_technical_notes tool walks the directory with an async generator that yields one file path at a time, scoring each file with a simple weighted match count (filename_hits × 10 + content_hits). For a smarter scoring strategy, edit scoreFile — e.g. weight matches in markdown headers higher, or plug in a real tokenizer.

Extending it

• Different scoring — edit scoreFile in src/index.ts.

• More extensions — add to the ALLOWED_EXTENSIONS set.

• More tools — call server.registerTool(...) again with the same shape as the existing two. The SDK handles schema validation via Zod.

Troubleshooting

License

MIT — see LICENSE.