Content
# Tool List
Unofficial Yinxiang (Evernote China) MCP Server. Exposes operations on notebooks, native super notes, raw ENML, and resource attachments via stdio.
> This project is not an official Evernote or Yinxiang project and does not represent official endorsement.
## Installation
```bash
npx -y @yanghechuan/yinxiang-mcp
```
Recommended to lock the version:
```bash
npx -y @yanghechuan/yinxiang-mcp@0.7.0
```
## Authentication
The current version uses Direct Token authentication, and OAuth is not yet implemented.
Two environment variables are required:
- `YINXIANG_DEV_TOKEN`: Developer Token applied from <https://dev.yinxiang.com>
- `YINXIANG_NOTESTORE_URL`: NoteStore URL, e.g., `https://app.yinxiang.com/shard/sXX/notestore`
## MCP Configuration
```json
{
"mcpServers": {
"yinxiang": {
"command": "npx",
"args": ["-y", "@yanghechuan/yinxiang-mcp@0.7.0"],
"env": {
"YINXIANG_DEV_TOKEN": "<your-token>",
"YINXIANG_NOTESTORE_URL": "https://app.yinxiang.com/shard/sXX/notestore"
}
}
}
}
```
## Tool List
### Notebooks and Stacks
- `list-notebooks`: List notebooks, including `guid`, `stack`, default notebook flag, and updated metadata.
- `get-notebook`: Read a single notebook's metadata by `guid`.
- `create-notebook`: Create a notebook, optionally adding it to a stack.
- `update-notebook`: Rename a notebook or update its stack, requires `confirm=true`.
- `delete-notebook`: Delete a notebook, requires `confirm=true` and `confirmGuid === guid`; non-empty notebooks also require `force=true`.
- `list-stacks`: Infer a list of stacks from notebooks' `stack` fields.
- `create-stack`: Create a stack by adding an existing notebook to it, requires `confirm=true`.
- `rename-stack`: Update the `stack` field of group notebooks to rename a stack, requires `confirm=true`.
- `delete-stack`: Clear the `stack` field of group notebooks to delete a stack, does not delete notebooks, requires `confirm=true`.
- `move-notebook-to-stack`: Move a single notebook into a specified stack, requires `confirm=true`.
- `remove-notebook-from-stack`: Move a single notebook out of its current stack, requires `confirm=true`.
### Notes
- `find-notes`: Search note metadata by Evernote search syntax and/or notebook GUID.
- `get-note-raw`: Read raw ENML, notebook GUID, tags, and attributes without Markdown conversion.
- `create-super-note`: Create a Yinxiang super note using the native block model.
- `update-super-note`: Overwrite a note's body using the native block model, requires `confirm=true`.
- `append-super-note-blocks`: Append native blocks to an existing ENML while preserving it, requires `confirm=true`.
- `replace-super-note-block`: Replace a native block by `blockId`, requires `confirm=true`.
- `delete-super-note-block`: Delete a native block by `blockId`, requires `confirm=true`.
- `replace-note-enml`: Overwrite a note's body with complete ENML or `en-note` internal body, requires `confirm=true`.
- `clone-note`: Clone ENML body and note metadata without Markdown conversion.
- `attach-file`: Append a local file as an Evernote Resource and add a matching `<en-media>` to the body, requires `confirm=true`.
- `export-note-resource`: Export a single resource by `resourceGuid` or MD5 `hash`.
- `delete-note-resource`: Delete a single resource and matching `<en-media>` by `resourceGuid` or MD5 `hash`, requires `confirm=true`.
- `move-note`: Move a note to another notebook without modifying its title and body, requires `confirm=true`.
- `clear-note-content`: Clear a note's body while preserving its title and notebook, requires `confirm=true`.
- `delete-note`: Move a note to the trash, requires `confirm=true`.
- `expunge-note`: Permanently delete a note, requires `confirm=true` and `confirmGuid === guid`.
## Native Block Model
`create-super-note`, `update-super-note`, and `append-super-note-blocks` accept an array of `blocks`. Strings are treated as ordinary paragraphs; object examples:
```json
[
{
"type": "heading",
"level": 2,
"id": "stable-block-id",
"runs": [
{ "text": "Blue bold title", "bold": true, "color": "#1677ff" }
]
},
{
"type": "paragraph",
"runs": [
{ "text": "Ordinary text " },
{ "text": "Red bold", "bold": true, "color": "#d4380d" },
{ "text": " Large text", "fontSize": 22 },
{ "text": " Link", "href": "https://example.com?a=1&b=2" }
]
},
{
"type": "todo",
"checked": false,
"runs": [{ "text": "To-do item" }]
},
{
"type": "table",
"id": "table-1",
"header": true,
"rows": [
[{ "text": "Name" }, { "text": "Status" }],
[{ "text": "Task A" }, { "text": "Done", "color": "#52c41a" }]
]
}
]
```
Supported block types: `heading`, `paragraph`, `blockquote`, `code`, `divider`, `todo`, `bulleted_list`, `numbered_list`, `table`.
Supported text styles: `bold`, `italic`, `underline`, `strike`, `code`, `color`, `backgroundColor`, `fontSize`, `href`.
Colors must use `#RRGGBB`; `fontSize` must be an integer between 8 and 72. The default font size for the body is 16px. Titles use the client's title level by default, only overriding the internal text when explicitly passing `fontSize`.
Table blocks must provide a stable `id` for easy editing/deletion of the entire table using `replace-super-note-block` or `delete-super-note-block`.
## File Resources
`attach-file` reads a local file, calculates its MD5, creates an Evernote Resource, and appends a matching `<en-media>` to the body. MIME is automatically inferred from the extension, but can also be explicitly passed.
```json
{
"guid": "note-guid",
"filePath": "/tmp/demo.png",
"fileName": "demo.png",
"confirm": true
}
```
Resources can be exported and deleted by `resourceGuid` or MD5 `hash`.
## Local Development
```bash
npm install
cp .env.example .env
npm test
npm run verify
npm start
```
`npm run verify` is a read-only verification: it lists notebooks to verify that the token and NoteStore URL are available.
## Publishing
```bash
npm test
npm pack --dry-run
npm publish --access public
```
Ensure that the npm tarball does not include `.env`, real tokens, logs, or private note content before publishing.
## Limitations
- Uses `evernote@2.0.5`, which is based on the older EDAM API.
- Evernote/Yinxiang stacks are not independent entities; this project implements stack management through notebooks' `stack` fields.
- Native super note tools do not convert through Markdown, suitable for preserving rich text styles like bold, color, links, to-dos, and tables.
- Markdown compatibility functions are retained internally but not exposed as MCP tools to avoid misuse that could lead to loss of rich text styles.
- Resource tools support local images, audio, and general attachments, allowing export and deletion by single resource.
## Security
Do not submit real Developer Tokens, bound account NoteStore URLs, request logs, or exported note content. See [SECURITY.md](SECURITY.md) for more information.
## Open-Source License
This project is under the MIT License. See [LICENSE](LICENSE) for the full license text.
