@f17/notsy-mcp

Official Model Context Protocol (MCP) stdio server for Notsy. Exposes the Notsy Integration API to MCP-capable AI clients (Claude Code, Gemini CLI, Codex, and any other client that speaks MCP over stdio).

The server is a thin adapter — it authenticates with a user-created Notsy API token and forwards each MCP tool call to https://api.notsy.app/api/integration/v1.

Status: beta. Public API surface (tool names, schemas, env variables) is covered by SemVer once 1.0.0 ships. Until then, expect minor breaking changes on minor bumps.

Quick start

For a new machine, end-to-end:

# 1. Make sure Node >= 20 is installed
node --version

# 2. Get an API token from notsy.app -> Settings -> API tokens

# 3. Add the server to your MCP client (Claude Code example)
claude mcp add notsy --transport stdio --scope user \
  -e NOTSY_API_TOKEN=ntsy_xxx... \
  -- npx -y @f17/notsy-mcp

Full setup for Claude Code, Gemini CLI, and Codex is in USAGE.md.

Tools

| Tool | Required scope(s) on the API token | Description | | --- | --- | --- | | notsy_list_projects | projects:read | List active projects granted to the token. | | notsy_create_note | notes:create (+ project grant if projectId is set) | Create a note. Supports externalId for retry-safe idempotency. | | notsy_list_notes | notes:read:self or notes:read:project | List notes visible to the token. Paginated; optional filters: projectId, unassigned, createdByToken. projectId + unassigned=true is rejected. | | notsy_get_note | notes:read:self or notes:read:project | Fetch one note by ULID. | | notsy_update_note | notes:update:self or notes:update:project | Update name and/or body of one note. | | notsy_assign_note_to_project | notes:assign:project (+ project grant) | Move an accessible note into a granted project. |

All tools return JSON in MCP text content. On API errors the result is returned with isError: true and a short, model-readable message (no token leakage).

Environment

| Variable | Required | Default | Description | | --- | --- | --- | --- | | NOTSY_API_TOKEN | yes | — | API token created in Notsy -> Settings -> API tokens. Stripped from process.env after read. | | NOTSY_API_BASE_URL | no | https://api.notsy.app/api | API root. Must be https:// (or http://localhost/127.0.0.1 for development). Other URLs are rejected. | | NOTSY_API_TIMEOUT_MS | no | 30000 | Per-request timeout. Must be an integer between 1000 and 120000. |

MCP client config (manual)

{
  "mcpServers": {
    "notsy": {
      "command": "npx",
      "args": ["-y", "@f17/notsy-mcp"],
      "env": {
        "NOTSY_API_TOKEN": "YOUR_NOTSY_API_TOKEN"
      }
    }
  }
}

Pin to a specific major: ["-y", "@f17/notsy-mcp@0"].

Security

• The server never logs the token. It is sent only in Authorization: Bearer ... to the configured NOTSY_API_BASE_URL.
• NOTSY_API_TOKEN is deleted from process.env immediately after read so it cannot be inherited by child processes or surfaced in crash dumps.
• NOTSY_API_BASE_URL is validated; non-HTTPS hosts outside localhost are rejected to prevent accidental forwarding of the bearer token.
• Use user/global MCP scope (not project scope) for real tokens so they are not committed to a repo.
• Tokens are scoped and revocable. Rotate via Notsy -> Settings -> API tokens.

Issues and contact

Issues, feature requests, and security reports: [email protected].

Notice

• The MIT license covers the source code of this MCP adapter, not the Notsy service. Use of the Notsy API requires a Notsy account and is governed by the Notsy Terms of Service at https://notsy.app/l/regulamin.
• "Notsy" is a trademark of F17. The MIT license does not grant trademark rights. Forks must not use the "Notsy" name in a way that implies official endorsement.
• This package is provided as-is. For service availability and SLA see the Notsy ToS; for adapter bugs use the issue tracker / contact email above.

License

MIT — see LICENSE.