pip install reminderit-mcp: a developer guide to the MCP package

reminderit-mcp is the Python package behind ReminderIt's Model Context Protocol server. It is MIT-licensed, published on PyPI, and ships both transports: stdio for a local client like Claude Desktop, and HTTP for a hosted, multi-user deployment. The managed server at mcp.reminderit.com runs this same package in HTTP mode.

Do you actually need this package?

Probably not, and it is worth being honest about that. If you just want Claude to schedule your reminders, add https://mcp.reminderit.com as a custom connector instead — it is a browser sign-in with no key to manage and nothing to keep running.

This package is for the cases the hosted connector does not cover:

• A headless box, cron job or CI runner that has no browser to complete an OAuth flow.
• An MCP client that only speaks stdio and cannot reach a remote server.
• You want to add your own tools on top, or wrap endpoints the hosted server does not expose.
• You would rather not route your traffic through our MCP host at all.

How do you install and run it?

One command, then one environment variable. The package requires Python 3.11 or newer and pulls in mcp[cli], httpx and uvicorn.

pip install reminderit-mcp
export REMINDERIT_API_KEY="rmt_your_key_here"
reminderit-mcp

Generate the key at reminderit.com/api-keys. Running with no transport argument starts stdio mode, which reads JSON-RPC from stdin and writes to stdout — there is no port and nothing to visit in a browser. If REMINDERIT_API_KEY is missing the process exits immediately with a message telling you where to get one, rather than starting and failing on the first call.

Two other variables are read, both optional:

• REMINDERIT_API_URL — defaults to https://api.reminderit.com. Point it at a local backend when you are developing against one.
• PORT — HTTP mode only, defaults to 8080.

How do you wire it into Claude Desktop?

Add it to claude_desktop_config.json and restart the app. On macOS that file lives at ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows, %APPDATA%\Claude\claude_desktop_config.json.

{
  "mcpServers": {
    "reminderit": {
      "command": "reminderit-mcp",
      "env": {
        "REMINDERIT_API_KEY": "rmt_your_key_here"
      }
    }
  }
}

If reminderit-mcp is not on the PATH Claude Desktop sees — common when you installed into a virtualenv — give the absolute path to the entry point instead, for example /Users/you/.venvs/ri/bin/reminderit-mcp. A server that fails to start shows up as a missing connector rather than an error, so check that first.

You get the same 25 tools as the hosted connector: scheduling and editing reminders, pausing and skipping, listing what is due, recent call outcomes, usage, the voice controls, and recipient management.

How do you run it as a hosted HTTP server?

reminderit-mcp http starts a Starlette app under Uvicorn on port 8080. The difference that matters is where the key comes from: HTTP mode resolves a key per request, so one process serves many users and no key sits in the environment.

PORT=8080 reminderit-mcp http

curl -s localhost:8080/health

Each request carries either Authorization: Bearer rmt_xxx or X-API-Key: rmt_xxx. The routes are:

• /mcp — the MCP streamable-HTTP endpoint. A plain POST without the streaming Accept header returns 406, which is the protocol working, not a fault.
• /health — returns 200 when the server is up.
• /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource — the discovery documents an MCP client reads to start an OAuth flow.

Two environment variables exist specifically for exposing it safely: MCP_ALLOWED_HOSTS (default mcp.reminderit.com,localhost,127.0.0.1) and MCP_ALLOWED_ORIGINS (default *). Set both before you put an instance on the public internet — the host allowlist is what stops a Host-header rewrite pointing your server somewhere unintended.

How should you handle the API key?

Treat rmt_ keys like any other production credential: an environment variable or a secret manager, never a committed file. A leaked key can place real phone calls against your account and draw down your quota.

Three specifics worth knowing:

• The Claude Desktop config file is plain text on disk. That is acceptable on a personal laptop with full-disk encryption; it is not a place for a key shared across a team.
• Prefer HTTP mode for anything multi-user. Per-request keys mean one person's key is never in a process another person can reach.
• Rotate from the dashboard. Keys are revoked at reminderit.com/api-keys, and revocation takes effect on the next call.

How do you add your own tool?

The server is built with FastMCP, so a tool is a decorated async function. The package wraps the ReminderIt REST API, which means anything the API can do can become a tool in a few lines:

from reminderit_mcp.server import mcp, _client

@mcp.tool()
async def reminders_due_today() -> str:
    """Return only the reminders that fire before midnight."""
    async with _client() as c:
        r = await c.get("/reminders/upcoming", params={"limit": 50})
    ...

The source is at github.com/Venkatnvs/ReminderIt under mcp-server/. If you would rather skip MCP entirely, the REST API underneath is documented at reminderit.com/developers/api and is the same surface every one of these tools calls.

One rule applies whatever you build on top: these are real outbound calls to real phone numbers. Get the timezone and the hour right before you schedule anything, and never put a third party's number on a reminder without going through add_recipient, which places a consent verification call first.