Metadata-Version: 2.4
Name: memos-fastmcp
Version: 0.2.3
Summary: MCP server for Memos built with FastMCP - self-hosted note-taking tool
Author: memos-mcp contributors
License: MIT
License-File: LICENSE
Keywords: ai,claude,mcp,memos,note-taking
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: fastmcp>=3.0.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic-settings>=2.13.0
Requires-Dist: pydantic>=2.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.20.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
Requires-Dist: pytest>=9.0.0; extra == 'dev'
Requires-Dist: respx>=0.23.0; extra == 'dev'
Requires-Dist: ruff>=0.15.0; extra == 'dev'
Description-Content-Type: text/markdown

# Memos MCP Server

[![PyPI](https://img.shields.io/pypi/v/memos-fastmcp)](https://pypi.org/project/memos-fastmcp/)
[![Python](https://img.shields.io/pypi/pyversions/memos-fastmcp)](https://pypi.org/project/memos-fastmcp/)
[![License](https://img.shields.io/github/license/Jiraiya8/memos-mcp)](https://github.com/Jiraiya8/memos-mcp)

**English | [中文](README_CN.md)**

MCP server for [Memos](https://github.com/usememos/memos) - the open-source, self-hosted note-taking tool. Built with [FastMCP](https://github.com/prefecthq/fastmcp).

## Features

### Tools

**Memo CRUD:**
- `create_memo` - Create a new memo with content, visibility, and tags
- `get_memo` - Get a memo by ID
- `update_memo` - Update memo content, visibility, or pinned status
- `delete_memo` - Delete a memo
- `list_memos` - List memos with filters (state, custom filter)
- `search_memos` - Search memos by content or tags

**Tag Management:**
- `list_tags` - List all tags with usage counts
- `rename_tag` - Rename a tag across all memos
- `delete_tag` - Delete a tag from all memos

**Visibility Control:**
- `set_visibility` - Set memo visibility (PRIVATE, PROTECTED, PUBLIC)
- `list_public_memos` - List all public memos
- `list_private_memos` - List all private memos

### Resources

- `memos://list` - Recent 20 memos summary (ID, title, tags, time, visibility)
- `memos://{memo_id}` - Full details of a specific memo
- `memos://tags` - All tags with usage counts
- `memos://stats` - Statistics (total memos, by visibility/state, tags count, pinned)

### Prompts

- `search_by_tag` - Quick search for memos with a specific tag
- `create_quick_note` - Create a simple memo with optional tag
- `find_recent_notes` - Find memos from past N days
- `organize_by_visibility` - Review and organize memos by visibility
- `update_memo_prompt` - Update a specific memo's content with verification

## Installation

```bash
# Using pip
pip install memos-fastmcp

# Using uvx (recommended)
uvx memos-fastmcp
```

## Configuration

### Get API Token

1. Open your Memos instance
2. Go to Settings > API Keys
3. Generate a new API token

### Environment Variables

```bash
MEMOS_URL=http://your-memos-instance:5230
MEMOS_TOKEN=your-api-token
```

Optional:
```bash
MEMOS_API_VERSION=v1          # Default: v1
MEMOS_REQUEST_TIMEOUT=30.0    # Default: 30.0 seconds
DISPLAY_STYLE=list            # Default: list (options: list, table)
```

### Output Format

Query tools (`list_memos`, `search_memos`, `get_memo`, `list_public_memos`, `list_private_memos`) return Markdown format with two display styles:

| Style | Description |
|-------|-------------|
| `list` | Detailed list items with full timestamps and status indicators (default) |
| `table` | Compact table format for quick scanning |

Example **list** style:
```markdown
## 📝 V2xmw6RkAEDo4TimKhCGNL

🔗 [查看详情](http://localhost:5230/memos/V2xmw6RkAEDo4TimKhCGNL)

**创建时间:** 2026-04-12 14:30:25
**状态:** 置顶 | 公开
**标签:** #work #project

项目计划已完成初步设计...
```

Example **table** style:
```markdown
| ID | 创建时间 | 状态 | 标签 | 内容 |
|----|----------|------|------|------|
| V2xmw6RkAEDo4TimKhCGNL | 2026-04-12 | 置顶 \| 公开 | #work #project | 项目计划已完成... |
```

**Notes:**
- ID column is not truncated (easy to copy for subsequent operations)
- Content truncated: 200 chars in list style, 50 chars in table style
- Hyperlinks point to browser-accessible memo detail pages

## Usage with MCP Clients

### Claude Desktop / Claude Code

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "memos": {
      "command": "uvx",
      "args": ["memos-fastmcp"],
      "env": {
        "MEMOS_URL": "http://your-memos-instance:5230",
        "MEMOS_TOKEN": "your-api-token"
      }
    }
  }
}
```

For Claude Desktop, place this in:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

For Claude Code, place this in `.claude/settings.json` in your project.

### Other MCP Clients

```bash
# Run directly with environment variables
MEMOS_URL=http://your-memos-instance:5230 \
MEMOS_TOKEN=your-api-token \
uvx memos-fastmcp
```

## Example Usage

Once configured, you can interact with Memos through Claude:

```
User: "Create a memo about my project plan with tag 'work'"
Claude: [Uses create_memo tool] "Created memo with ID: abc123..."

User: "Search for all memos tagged 'work'"
Claude: [Uses search_memos tool] "Found 5 memos tagged 'work'..."

User: "What are my most used tags?"
Claude: [Uses memos://tags resource] "Your top tags are: work (12), ideas (8)..."

User: "Show me recent memos from the past week"
Claude: [Uses find_recent_notes prompt] "Here are 7 memos from the past week..."

User: "Pin memo abc123"
Claude: [Uses update_memo tool] "Successfully pinned memo abc123"
```

## Development

### Local Setup

```bash
git clone https://github.com/Jiraiya8/memos-mcp.git
cd memos-mcp

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run locally
MEMOS_URL=http://localhost:5230 MEMOS_TOKEN=your-token python -m memos_mcp.server
```

### Build & Publish

```bash
python -m build
twine upload dist/*
```

## API Compatibility

Compatible with Memos API v1. Requires Memos 0.22.0 or later.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Links

- [PyPI](https://pypi.org/project/memos-fastmcp/)
- [GitHub](https://github.com/Jiraiya8/memos-mcp)
- [Memos](https://github.com/usememos/memos)
- [FastMCP](https://github.com/prefecthq/fastmcp)