notmcp

What it is

notmcp is a reaction to a simple frustration: agents need tools, but most "tool systems" feel like you're installing a protocol.

In practice, most tools are just "call an API, handle auth, return something sane." So notmcp replaces the ceremony with the obvious thing: code.

When you ask your agent to "connect to PostHog" or "search my Gmail," it doesn't negotiate with a server. It writes (or reuses) a script that does the job, stores credentials safely, and runs it locally. The tool returns structured output, and your agent continues.

How it works

Tools live in a private directory under your home folder:

~/.claude/skills/notmcp/
├── SKILL.md          # Teaches your agent how to use notmcp
├── bin/
│   └── notmcp        # The CLI (stdlib Python, no dependencies)
├── scripts/          # Your tools live here
│   ├── posthog-get-users.py
│   └── gmail-search.py
└── .credentials      # API keys (chmod 600, never in repos)

Your agent discovers tools by running notmcp list. It runs them with notmcp run. It creates new ones with notmcp create.

Over time, your local notmcp library becomes an evolving SDK that keeps getting better.

The tool contract

Tools are just Python scripts with a header declaring what they need:

#!/usr/bin/env python3
"""
name: posthog-get-users
description: Fetch users from PostHog
credentials:
  - POSTHOG_API_KEY
"""
import json, os, sys

def main():
    inp = json.load(sys.stdin) if not sys.stdin.isatty() else {}
    api_key = os.environ["POSTHOG_API_KEY"]
    
    # Do the work...
    
    print(json.dumps({"users": [...]}))

if __name__ == "__main__":
    main()

• JSON in (stdin) → JSON out (stdout)
• Credentials injected as environment variables
• Logs go to stderr
• Exit 0 = success
• Stdlib only—no pip dependencies

Why not MCP?

MCP is great for structured tool ecosystems. But notmcp is for a different problem: most tools are simple, and the protocol overhead isn't worth it.

• No server to run – tools are scripts, not services
• No protocol to learn – JSON in, JSON out
• No dependency hell – stdlib Python only
• Debuggable – run any tool manually in your terminal
• Evolvable – your agent can improve tools over time

FAQ