# 印象笔记 MCP Server

基于印象笔记 Developer API 构建的 MCP (Model Context Protocol) Server，让 Claude 能够直接操作你的印象笔记账户。

## 功能

| Tool | 功能 |
|------|------|
| `yinxiang_list_notebooks` | 列出所有笔记本（含 GUID） |
| `yinxiang_list_notes` | 列出笔记，支持按笔记本过滤和分页 |
| `yinxiang_search_notes` | 全文检索笔记（支持印象笔记搜索语法） |
| `yinxiang_get_note` | 获取指定笔记的完整内容 |
| `yinxiang_create_note` | 创建新笔记（Markdown → ENML 自动转换） |
| `yinxiang_update_note` | 更新笔记标题或内容 |

## 快速开始

### 第一步：获取 Developer Token

1. 访问 https://app.yinxiang.com/api/DeveloperToken.action
2. 点击 "Create a developer token"
3. 复制以 `S=s1:` 开头的 Token，填入 `.env` 文件

### 第二步：安装依赖

```bash
cd ~/mcp-servers/yinxiang-mcp
uv venv --python 3.11
uv pip install -r requirements.txt
```

### 第三步：启动 HTTP Server

```bash
./start.sh       # 后台启动（端口 8765）
./status.sh      # 查看状态
./stop.sh        # 停止服务
```

### 第四步（可选）：开机自启

```bash
cp com.yinxiang.mcp.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.yinxiang.mcp.plist
```

## 接入 MCP 客户端

Server 启动后，所有支持 MCP 的客户端均可通过以下端点接入：

```
http://127.0.0.1:8765/mcp
```

### Claude Code

`~/.claude/settings.json` 中添加：

```json
"yinxiang": {
  "url": "http://127.0.0.1:8765/mcp"
}
```

### CatPaw / 其他 MCP 客户端

在客户端的 MCP 配置中填入：
- **类型**：Streamable HTTP
- **URL**：`http://127.0.0.1:8765/mcp`

## 搜索语法说明

印象笔记支持丰富的搜索语法：

| 语法 | 示例 | 说明 |
|------|------|------|
| 关键词 | `Python 学习` | 全文搜索 |
| `notebook:` | `notebook:工作` | 按笔记本名称 |
| `tag:` | `tag:重要` | 按标签 |
| `intitle:` | `intitle:会议记录` | 按标题关键词 |
| `created:` | `created:20240601` | 按创建日期 |
| `updated:` | `updated:20240101` | 按更新日期 |
| 组合使用 | `tag:工作 intitle:周报` | 多条件组合 |

## 注意事项

- **Token 安全**：Developer Token 有完整账户访问权限，请妥善保管，不要提交到代码仓库
- **API 频率限制**：印象笔记限制每小时每用户的 API 调用次数，个人正常使用不会触发
- **ENML 格式**：笔记内容使用 ENML（印象笔记 XML 格式），工具会自动完成 Markdown ↔ ENML 转换
- **中国版专用**：本服务器配置为印象笔记中国版（app.yinxiang.com），不兼容国际版 Evernote

## For AI Agents / 自动化安装指南

If a user asks you to install this MCP server, please follow these EXACT steps strictly:

1. **Clone & Setup Environment**:
   Clone the repository to a suitable location. Create a Python 3.11+ virtual environment (`python -m venv .venv` or `uv venv`) and install dependencies from `requirements.txt`.

2. **Ask for Developer Token (CRITICAL)**:
   You CANNOT generate the Evernote/Yinxiang developer token for the user. You MUST pause and ask the user to provide it.
   Provide them this exact link: `https://app.yinxiang.com/api/DeveloperToken.action`
   Wait for their reply with the token (starting with `S=s...`).

3. **Configure MCP Client (Use stdio mode)**:
   Once you have the token, DO NOT use the HTTP mode or `start.sh`. Configure the user's IDE/MCP Client using the `stdio` transport. 
   Set the configuration as follows:
   - Command: `/path/to/repo/.venv/bin/python` (use the absolute path to the venv python)
   - Arguments: `["/path/to/repo/server.py"]` (absolute path)
   - Environment Variables: `{"YINXIANG_TOKEN": "the_token_user_provided"}`

4. **Verify**:
   Inform the user that the installation is complete and the MCP is registered via `stdio`.