Notama MCP Server

MCP (Model Context Protocol) server for Notama, allowing AI agents to read and manipulate notes via the REST API.

Quick Start

No installation needed — just use npx:

npx notama-mcp --api-key ntm_YOUR_API_KEY

Generate an API key from Settings → API Keys in any Notama client (web, desktop, or mobile).

Transport Modes

Stdio Mode (Recommended for AI clients)

Runs as a stdio process launched directly by AI clients like Claude Desktop, VS Code Copilot, Cursor, and Windsurf. Uses API key authentication.

npx notama-mcp --api-key ntm_YOUR_API_KEY

Options:

--api-key <key>   Notama API key (ntm_...). Required.
--api-url <url>   Notama server API URL (default: https://my.notama.app/api)
--help, -h        Show help

HTTP Mode (for Docker / multi-user)

Runs as an HTTP server using Streamable HTTP transport. Best for Docker deployments and multi-user setups.

MCP Configuration

Claude Desktop

Edit your config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "notama": {
      "command": "npx",
      "args": ["notama-mcp", "--api-key", "ntm_YOUR_API_KEY"]
    }
  }
}

VS Code (GitHub Copilot)

Create .vscode/mcp.json in your project:

{
  "servers": {
    "notama": {
      "command": "npx",
      "args": ["notama-mcp", "--api-key", "ntm_YOUR_API_KEY"]
    }
  }
}

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "notama": {
      "command": "npx",
      "args": ["notama-mcp", "--api-key", "ntm_YOUR_API_KEY"]
    }
  }
}

Windsurf

{
  "mcpServers": {
    "notama": {
      "command": "npx",
      "args": ["notama-mcp", "--api-key", "ntm_YOUR_API_KEY"]
    }
  }
}

HTTP Mode (Advanced)

{
  "mcpServers": {
    "notama": {
      "url": "https://mcp.notama.app/mcp",
      "headers": {
        "Authorization": "Bearer ntm_YOUR_API_KEY"
      }
    }
  }
}

Environment Variables

Can be used instead of CLI flags:

| Variable | Description | Default | | ---------------- | ----------------------------------- | ------------------------ | | NOTAMA_API_KEY | Your API key (replaces --api-key) | — | | NOTAMA_API_URL | Server API URL (replaces --api-url) | https://my.notama.app/api |

API Key Authentication

Generate API keys from Settings → API Keys in any Notama client. Keys use the format ntm_<64 hex characters>.

For the HTTP mode endpoint, API keys can be provided via:

1. Authorization header (recommended): Authorization: Bearer ntm_abc123...
2. Query string (fallback): ?api_key=ntm_abc123...

Self-Hosting

If you self-host Notama, specify your server URL:

npx notama-mcp --api-key ntm_YOUR_KEY --api-url https://your-server.com/api

Docker Deployment (HTTP Mode)

The MCP HTTP server is included in the docker-compose stack:

mcp:
  build: ./mcp
  ports:
    - "3100:3100"
  environment:
    NOTAMA_API_URL: http://server:8081/api
  depends_on:
    - server

docker compose up -d

Available Tools

Notes

| Tool | Description | | ------------------ | ------------------------------------------------ | | get_note | Get a note by ID with content as markdown | | list_notes | List notes, optionally filtered by parent folder | | create_note | Create a new note with markdown content | | update_note | Update a note (auto-handles version concurrency) | | delete_note | Archive (soft-delete) a note | | get_recent_notes | Get recently updated notes | | get_pinned_notes | Get all pinned notes | | quick_capture | Quickly create a note with content |

Search

| Tool | Description | | -------------- | --------------------------------- | | search_notes | Full-text search across all notes |

Folders

| Tool | Description | | --------------- | --------------------------------- | | list_folders | List all folders | | create_folder | Create a new folder | | move_note | Move a note to a different folder |

Tags

| Tool | Description | | ---------------------- | --------------------------------- | | list_tags | List all tags | | create_tag | Create a new tag | | add_tag_to_note | Add a tag to a note | | remove_tag_from_note | Remove a tag from a note | | get_notes_by_tag | Get all notes with a specific tag |

Testing

MCP Inspector

npx @modelcontextprotocol/inspector npx notama-mcp --api-key ntm_YOUR_API_KEY

Opens a browser UI to interactively test all tools.

Links

• npm: npmjs.com/package/notama-mcp
• Notama: notama.app
• Web App: my.notama.app