Affected by 
README
¶
MCP Server
This package implements a Model Context Protocol (MCP) server embedded in the Memos HTTP process. It exposes memo operations as MCP tools, making Memos accessible to any MCP-compatible AI client (Claude Desktop, Cursor, Zed, etc.).
Endpoint
POST /mcp (tool calls, initialize)
GET /mcp (optional SSE stream for server-to-client messages)
DELETE /mcp (optional session termination)
Transport: Streamable HTTP (single endpoint, MCP spec 2025-03-26).
Tool Filtering
The default /mcp endpoint exposes all tools. Clients can opt into a smaller
tool surface with GitHub-style headers or route aliases:
| Control | Description |
|---|---|
X-MCP-Readonly: true |
Hide and block mutating tools |
X-MCP-Toolsets: memos,tags,attachments,relations,reactions |
Limit the default tool list to selected toolsets |
X-MCP-Tools: list_tags,get_memo |
Add specific tools to the selected toolset list |
X-MCP-Exclude-Tools: delete_memo |
Remove specific tools |
Equivalent aliases:
/mcp/readonly
/mcp/x/{toolsets}
/mcp/x/{toolsets}/readonly
Examples:
/mcp/x/memos,tags/readonly
X-MCP-Toolsets: memos
X-MCP-Tools: list_tags
X-MCP-Exclude-Tools: delete_memo
Capabilities
The server advertises the following MCP capabilities:
| Capability | Enabled | Details |
|---|---|---|
| Tools | Yes | List changed notifications supported |
| Resources | Yes | Subscribe + list changed supported |
| Prompts | Yes | List changed notifications supported |
| Logging | Yes | Structured log events |
Authentication
Public reads can be used without authentication. Personal Access Tokens (PATs) or short-lived JWT session tokens are required for:
- Reading non-public memos or attachments
- Any tool that mutates data
When authenticating, send a Bearer token:
Authorization: Bearer <your-PAT>
PATs are long-lived tokens created in Settings → My Account → Access Tokens. Short-lived JWT session tokens are also accepted. Requests with an invalid token receive HTTP 401.
Origin Validation
For Streamable HTTP safety, requests with an Origin header must be same-origin with the current request host or match the configured instance-url. Requests without an Origin header, such as desktop MCP clients and CLI tools, are allowed.
Tools
Memo Tools
| Tool | Description | Required params | Optional params |
|---|---|---|---|
list_memos |
List memos | — | page_size, page, state, order_by_pinned, filter (supported subset of standard CEL syntax) |
get_memo |
Get a single memo | name |
— |
search_memos |
Full-text search | query |
— |
create_memo |
Create a memo | content |
visibility |
update_memo |
Update a memo | name |
content, visibility, pinned, state |
delete_memo |
Delete a memo | name |
— |
list_memo_comments |
List comments | name |
— |
create_memo_comment |
Add a comment | name, content |
— |
Tag Tools
| Tool | Description | Required params |
|---|---|---|
list_tags |
List all tags with counts | — |
Attachment Tools
| Tool | Description | Required params | Optional params |
|---|---|---|---|
list_attachments |
List user's attachments | — | page_size, page, memo |
get_attachment |
Get attachment metadata | name |
— |
delete_attachment |
Delete an attachment | name |
— |
link_attachment_to_memo |
Link attachment to a memo you own | name, memo |
— |
Relation Tools
| Tool | Description | Required params | Optional params |
|---|---|---|---|
list_memo_relations |
List relations (refs + comments) | name |
type |
create_memo_relation |
Create a reference relation from a memo you own to a memo you can read | name, related_memo |
— |
delete_memo_relation |
Delete a reference relation from a memo you own | name, related_memo |
— |
Reaction Tools
| Tool | Description | Required params |
|---|---|---|
list_reactions |
List reactions on a memo | name |
upsert_reaction |
Add a reaction emoji | name, reaction_type |
delete_reaction |
Remove a reaction | id |
Resources
| URI Template | Description | MIME Type |
|---|---|---|
memo://memos/{uid} |
Memo content with YAML frontmatter | text/markdown |
Prompts
| Prompt | Description | Arguments |
|---|---|---|
capture |
Quick-save a thought as a memo | content (required), tags, visibility |
review |
Search and summarize memos on a topic | topic (required) |
daily_digest |
Summarize recent memo activity | days |
organize |
Suggest tags/relations for unorganized memos | scope |
Resource Names
- Memos:
memos/<uid>(e.g.memos/abc123) - Attachments:
attachments/<uid>(e.g.attachments/def456)
Connecting Claude Code
claude mcp add --transport http memos http://localhost:5230/mcp \
--header "Authorization: Bearer <your-PAT>"
Use --scope user to make it available across all projects:
claude mcp add --scope user --transport http memos http://localhost:5230/mcp \
--header "Authorization: Bearer <your-PAT>"
Package Structure
| File | Responsibility |
|---|---|
mcp.go |
MCPService struct, constructor, route registration, auth middleware, tool filtering |
tool_metadata.go |
Toolsets, read-only metadata, annotations, structured result helpers |
api_helpers.go |
Conversion helpers for calling API service methods from MCP tools |
tools_memo.go |
Memo CRUD tools + helpers (JSON types, visibility/access checks) |
tools_tag.go |
Tag listing tool |
tools_attachment.go |
Attachment listing, metadata, deletion, linking tools |
tools_relation.go |
Memo relation (reference) tools |
tools_reaction.go |
Reaction (emoji) tools |
resources_memo.go |
Memo resource template handler |
prompts.go |
Prompt handlers (capture, review, daily_digest, organize) |
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type MCPService ¶
type MCPService struct {
// contains filtered or unexported fields
}
func NewMCPService ¶
func NewMCPService(profile *profile.Profile, store *store.Store, secret string, apiV1Service *apiv1.APIV1Service) *MCPService
func (*MCPService) RegisterRoutes ¶
func (s *MCPService) RegisterRoutes(echoServer *echo.Echo)
Source Files