Notes & Tasks MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Notes & Tasks MCP Server
An MCP server that gives AI assistants like Claude safe access to your personal notes and to-do list. You can say "add a task to send the salary slips by Friday" or "what did I write about the bank loan?", and the assistant does it with your real data.
It follows the current MCP specification (2026-07-28): tools, resources and prompts over Streamable HTTP and stdio, protected with OAuth 2.1 exactly as the spec's authorization rules describe, with scoped, deny-by-default permissions.
Built with NestJS 12, @nestjs/mcp (on the official MCP TypeScript SDK v2), oidc-provider and PostgreSQL.
When an AI app connects, the user signs in and chooses exactly what it may do. Here, "edit tasks" is unticked, so the app gets read-only access to tasks.
What the AI can do
Tools
Tool | What it does | Scope | Hints |
| Full-text search by words and/or tag, returns previews |
| read-only |
| One note with its full Markdown body |
| read-only |
| New note with title, Markdown body, tags |
| |
| Change fields, or |
| destructive |
| Delete a note (the AI is told to confirm first) |
| destructive, idempotent |
| Filter by status, due date (overdue, today, next 7 days) and priority |
| read-only |
| New task with due date, priority, optional linked note |
| |
| Change fields, reopen |
| destructive, idempotent |
| Mark done (safe to repeat) |
| idempotent |
| Delete a task |
| destructive, idempotent |
Every tool has a typed output schema (structuredContent), so clients get real JSON back, not just text.
Resources
URI | What it is |
| One note as Markdown |
| All pinned notes, as standing context |
| All open tasks as a Markdown checklist |
Prompts
Prompt | What it does |
| Pulls in overdue, today's and upcoming tasks and asks for a plan for today |
| What got done this week, what's still open, recent notes, top 3 priorities |
| Summarises notes (optionally by tag) and offers to turn action items into tasks |
Related MCP server: MCP OAuth Starter
How connecting works
When you add this server to an MCP client, it finds out how to log in by itself. Nothing needs to be configured by hand:
sequenceDiagram
participant C as MCP client (e.g. Claude)
participant M as /mcp (resource server)
participant A as OAuth server (/oauth)
participant U as User's browser
C->>M: POST /mcp (no token)
M-->>C: 401 + WWW-Authenticate: resource_metadata=...
C->>M: GET /.well-known/oauth-protected-resource/mcp
M-->>C: authorization_servers, scopes_supported
C->>A: GET /.well-known/oauth-authorization-server
C->>A: register (Client ID Metadata Document, or dynamic registration)
C->>U: open /oauth/authorize (PKCE S256, resource=/mcp)
U->>A: sign in, tick allowed scopes
A-->>C: redirect with code (+ iss, state)
C->>A: POST /oauth/token (code + PKCE verifier)
A-->>C: JWT access token (aud = /mcp) + refresh token
C->>M: POST /mcp with Bearer tokenDesign decisions
These are the choices worth talking about, and why I made them.
Decision | Why |
The MCP endpoint is an OAuth "resource server" | It only checks tokens: signature, issuer, audience (must be this server's |
A real OAuth library instead of hand-written token code | The SDK's built-in OAuth server is deprecated, and the spec recommends a dedicated one. |
PKCE S256 required for every client | MCP clients are apps on the user's device. They can't keep a secret, so PKCE proves the app that started the login is the one finishing it. |
Both ways for a new client to register | Client ID Metadata Documents (the client ID is an HTTPS URL describing the app, which the latest spec prefers) and Dynamic Client Registration (what older clients use). |
Scopes the user can untick | The consent screen lists each permission. Unticked ones are recorded as declined, so the app gets a smaller token instead of being asked again. |
Deny by default, and write includes read | Every tool, resource and prompt declares its scopes. A call without them gets HTTP 403 |
Every query is filtered by the user | The user ID comes from the verified token, and every database query includes it. Another user's note simply doesn't exist: there's no "403 forbidden" that would hint it does. |
Stateless HTTP (protocol 2026-07-28) | No sessions to store, so it runs behind any load balancer. Older (2025) clients are still served, statelessly. |
Host header checks | Protects against DNS-rebinding attacks on servers running on localhost, as the spec requires. |
Refresh tokens rotate | Each refresh gives a new refresh token. Reusing an old one fails, so a stolen refresh token stops working. |
The OAuth server's data is in Postgres | Codes, grants, sessions and refresh tokens survive restarts and work across several instances. Using a code twice is blocked atomically, even if two requests race. |
Tools are written for the AI | Clear descriptions, behaviour hints ( |
The login pages are plain HTML | Server-rendered forms that work without JavaScript. Every value is escaped, the forms are tied to a cookie (so another site can't submit them), and sign-in is rate-limited. |
Passwords use scrypt | With OWASP's recommended settings and a random salt. Unknown emails still go through a full hash check, so response times don't reveal which accounts exist. |
Spec checklist
MCP authorization requirement | Where |
Protected Resource Metadata (RFC 9728) |
|
401 with | every unauthenticated |
Authorization Server Metadata (RFC 8414) |
|
PKCE with S256 | required for all clients; only S256 accepted |
Resource indicators (RFC 8707) and audience checks | tokens are issued for |
| yes |
Client ID Metadata Documents / Dynamic Client Registration | both |
403 | per tool, resource and prompt |
Tokens never in the URL | header only ( |
stdio takes credentials from the environment |
|
Run it
npm install
npm run keys:generate # prints OAUTH_SIGNING_KEY and COOKIE_SECRET
cp .env.example .env # then paste those two lines into .env
docker compose up -d postgres
npm run start:dev # MCP: http://localhost:3000/mcpOr everything in Docker (after putting the keys in .env):
docker compose up --buildConnect it to Claude Code
claude mcp add --transport http notes-tasks http://localhost:3000/mcpThen run /mcp in Claude Code and choose Authenticate. A browser opens to sign up and pick permissions.
Try it with the MCP Inspector
npm run inspector # then connect to http://localhost:3000/mcpUse it over stdio (Claude Desktop and others)
Create an account first (by connecting once over HTTP), then add this to your client's MCP config:
{
"mcpServers": {
"notes-tasks": {
"command": "node",
"args": ["--env-file=/path/to/notes-tasks-mcp/.env", "/path/to/notes-tasks-mcp/dist/stdio.js"],
"env": { "STDIO_USER_EMAIL": "you@example.com" }
}
}
}Over stdio there is no OAuth: the MCP spec says local servers take credentials from the environment. The process acts as that one user.
Tests
npm test # unit tests
npm run test:e2e # end-to-end tests (needs: docker compose up -d postgres)The end-to-end tests run the real server over HTTP and go through the whole OAuth flow the way an MCP client would: discovery, registration, the real sign-up and consent forms (with cookies), code exchange, refresh. Then they call the tools with the token. They cover:
Discovery metadata, and 401 without a token
The full login flow, including the
issandstatechecksA reused authorization code, a wrong PKCE verifier, and a reused refresh token are all refused
Denying consent sends the user back with
access_denied; a wrong password stays on the login pageTokens for another audience, expired tokens, and forged tokens are refused
Every tool, resource and prompt works, and input is validated
One user can't read, find or delete another user's notes
Unticked scopes are really missing from the token, and calls that need them get 403
insufficient_scopewith the right challengewritescopes includeread
The unit tests cover the token checker, scope rules, password hashing and HTML escaping.
Project structure
src/
mcp/ MCP server setup, token verifier, scopes, prompts
notes/ notes: service (business logic) and MCP tools/resources
tasks/ tasks: service and MCP tools/resources
oauth/ OAuth server (oidc-provider), Postgres adapter, login/consent pages
users/ accounts and password hashing
database/ data source and migrations
main.ts HTTP entry point
stdio.ts stdio entry point
scripts/ key generation
test/ end-to-end tests and the test OAuth clientLicense
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
AI-powered to-do list: add, list, complete and organise tasks across lists from any assistant.
Personal AI memory: search and read your notes and todos; changes wait for your approval.
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to manage a user's personal task garden through OAuth, with tools for listing, creating, updating, and completing tasks, managing spaces, and searching notes.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants like ChatGPT and Claude to authenticate, access per-user notes, and read or write those notes on a user's behalf, with immediate access revocation.45 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to read, search, create, edit, move, and version Markdown notes, folders, tags, tasks, and attachments. It also supports generating meeting reports and bulk-importing notes through authenticated MCP connections.MIT
- AlicenseBqualityCmaintenanceExposes Microsoft To Do and Microsoft Planner over the Microsoft Graph API with delegated authentication, letting an assistant read and write personal tasks, checklists, and shared team tasks—including assigning Planner tasks to other people—and also search OneNote notebooks and pages read-only.38MIT