Mowen Note

Um servidor MCP para interagir com a API do Mowen Note, permitindo gerenciamento de notas e uploads de arquivos dentro de clientes MCP.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP Mowen Note

Este é um servidor baseado no Model Context Protocol (MCP) para interagir com o software Mowen Note. Através deste servidor, você pode criar, editar e gerenciar notas Mowen diretamente em aplicativos que suportam MCP (como Cursor, Claude Desktop, etc.).

Este projeto é uma colaboração entre a comunidade Yizhi Huohua e a Mowen.

🆕 Versão sem instalação disponível (adequada para iniciantes)

Como usar (exemplo no Windows)

Baixe mowen-mcp-server-windows-x64-v1.0.0.zip e extraia o mowen-mcp-server.exe
No cliente MCP, modifique o valor do comando para o caminho do arquivo mowen-mcp-server.exe

{
  "mcpServers": {
    "mowen-mcp-server": {
      "command": "D:\\mowen\\mowen-mcp-server.exe",
      "args": [],
      "env": {
        "MOWEN_API_KEY": "xxxxxxxxxxxxxxx"
      }
    }
  }
}

✨ Novidades da versão mais recente: suporte a upload de arquivos! Agora você pode inserir imagens, áudio e arquivos PDF nas notas, com suporte a upload de arquivos locais e URLs remotas.

🆕 Prévia de novos recursos (v0.2.0)

📁 Suporte a upload de arquivos

⚠️ Importante: o caminho do arquivo deve ser um caminho absoluto, pois o servidor MCP e o cliente são executados em diretórios de trabalho diferentes.

# 本地图片文件
{
    "type": "file",
    "file_type": "image",
    "source_type": "local",
    "source_path": "C:\\Users\\用户名\\Documents\\image.jpg",  # Windows绝对路径
    "metadata": {
        "alt": "图片描述",
        "align": "center"
    }
}

# 远程音频文件（URL不受路径限制）
{
    "type": "file",
    "file_type": "audio",
    "source_type": "url",
    "source_path": "https://example.com/audio.mp3",
    "metadata": {
        "show_note": "00:00 开始\n01:30 主要内容"
    }
}

📝 Citação de parágrafos

{
    "type": "quote",
    "texts": [
        {"text": "重要提醒：", "bold": true},
        {"text": "支持富文本格式的引用段落"}
    ]
}

🔗 Notas com links internos

{
    "type": "note",
    "note_id": "VPrWsE_-P0qwrFUOygGs8"
}

Recursos

🔗 Compatível com o protocolo MCP: suporta a versão mais recente do MCP 1.9.1
📝 Criar notas: formato de rich text unificado, com suporte a parágrafos, negrito, destaque, links, citações e notas com links internos
✏️ Editar notas: formato de rich text unificado, substitui completamente o conteúdo da nota
📁 Upload de arquivos: suporte a upload de imagens, áudio e PDF, tanto de arquivos locais quanto URLs remotas
💬 Citação de parágrafos: cria blocos de texto citados, com suporte a rich text
🔗 Notas com links internos: referencie outras notas, criando associações entre notas
🔒 Configurações de privacidade: defina a visibilidade da nota como pública, privada ou com regras
🔄 Gerenciamento de chaves: função de redefinição da chave da API
🎨 Interface unificada: todas as operações de notas usam o mesmo formato de parâmetros de rich text

Início rápido

Pré-requisitos

Python 3.10+
Conta de assinante Pro da Mowen (os recursos da API estão disponíveis apenas para assinantes Pro)
Chave da API da Mowen (obtenha no miniaplicativo Mowen)

Métodos de instalação

Método 1: Instalação a partir do código-fonte (recomendado)

Clone o projeto:

git clone https://github.com/z4656207/mowen-mcp-server.git
cd mowen-mcp-server

Instale as dependências:

pip install -e .

Método 2: Instale as dependências diretamente

pip install mcp httpx pydantic

Configurando a chave da API

Windows PowerShell

$env:MOWEN_API_KEY="你的墨问API密钥"

Linux/macOS

export MOWEN_API_KEY="你的墨问API密钥"

Configuração persistente

Crie o arquivo .env:

MOWEN_API_KEY=你的墨问API密钥

Configurando o cliente MCP

Método 1: Instalação via módulo (recomendado)

Se você usou pip install -e . para instalar, adicione nas configurações do Cursor:

{
  "mcpServers": {
    "mowen-mcp-server": {
      "command": "python",
      "args": ["-m", "mowen_mcp_server.server"],
      "env": {
        "MOWEN_API_KEY": "${env:MOWEN_API_KEY}"
      }
    }
  }
}

Método 2: Caminho direto do arquivo

Se você não tiver um pacote instalado, pode especificar diretamente o caminho do arquivo:

{
  "mcpServers": {
    "mowen-mcp-server": {
      "command": "python",
      "args": ["绝对路径/mowen-mcp-server/src/mowen_mcp_server/server.py"],
      "env": {
        "MOWEN_API_KEY": "${env:MOWEN_API_KEY}"
      }
    }
  }
}

Observação: substitua 绝对路径 pelo caminho real do seu projeto, por exemplo:

Windows: "D:/CODE/mowen-mcp-server/src/mowen_mcp_server/server.py"
macOS/Linux: "/home/user/mowen-mcp-server/src/mowen_mcp_server/server.py"

Ferramentas disponíveis

create_note

Cria uma nova nota Mowen usando o formato de rich text unificado

Parâmetros:

paragraphs (array, obrigatório): lista de parágrafos em rich text, cada parágrafo contém nós de texto
auto_publish (booleano, opcional): se deve publicar automaticamente, padrão é false
tags (array de strings, opcional): lista de tags da nota

Tipos de parágrafos suportados:

Parágrafo normal (padrão): {"texts": [...]}
Parágrafo de citação: {"type": "quote", "texts": [...]}
Nota com link interno: {"type": "note", "note_id": "笔记ID"}
Parágrafo de arquivo: {"type": "file", "file_type": "image|audio|pdf", "source_type": "local|url", "source_path": "绝对路径", "metadata": {...}}

Exemplo de formato de parágrafo:

[
  {
    "texts": [
      {"text": "普通文本"},
      {"text": "加粗文本", "bold": true},
      {"text": "高亮文本", "highlight": true},
      {"text": "链接文本", "link": "https://example.com"}
    ]
  },
  {
    "type": "quote",
    "texts": [
      {"text": "这是引用段落"},
      {"text": "支持富文本", "bold": true}
    ]
  },
  {
    "type": "note",
    "note_id": "VPrWsE_-P0qwrFUOygxxx"
  },
  {
    "type": "file",
    "file_type": "image",
    "source_type": "local",
    "source_path": "C:\\Users\\用户名\\Documents\\image.jpg",
    "metadata": {
      "alt": "图片描述",
      "align": "center"
    }
  }
]

Exemplo de texto simples:

[
  {
    "texts": [
      {"text": "这是一段简单的文本内容"}
    ]
  }
]

edit_note

Edita o conteúdo de uma nota existente usando o formato de rich text unificado

Parâmetros:

note_id (string, obrigatório): ID da nota a ser editada
paragraphs (array, obrigatório): lista de parágrafos em rich text, que substituirá completamente o conteúdo original

Observação: esta operação substitui completamente o conteúdo original da nota, não adiciona conteúdo. Suporta todos os tipos de parágrafos (parágrafo normal, parágrafo de citação, nota com link interno, parágrafo de arquivo).

set_note_privacy

Define as permissões de privacidade da nota

Parâmetros:

note_id (string): ID da nota
privacy_type (string): tipo de privacidade (public/private/rule)
no_share (booleano, opcional): se deve proibir compartilhamento (válido apenas para o tipo rule)
expire_at (inteiro, opcional): timestamp de expiração (válido apenas para o tipo rule, 0 significa nunca expira)

reset_api_key

Redefine a chave da API da Mowen

Observação: esta operação invalida imediatamente a chave atual

Exemplos de uso

Criar uma nota de texto simples

# 通过MCP工具调用
create_note(
    paragraphs=[
        {
            "texts": [
                {"text": "今天学习了Python编程，重点是异步编程概念"}
            ]
        }
    ],
    auto_publish=True,
    tags=["学习", "Python", "编程"]
)

Criar uma nota em rich text

# 通过MCP工具调用
create_note(
    paragraphs=[
        {
            "texts": [
                {"text": "重要提醒：", "bold": true},
                {"text": "明天的会议已改期"}
            ]
        },
        {
            "texts": [
                {"text": "详情请查看：", "highlight": true},
                {"text": "会议通知", "link": "https://example.com/meeting"}
            ]
        }
    ],
    auto_publish=True,
    tags=["会议", "通知"]
)

Criar uma nota complexa com citações e links internos

# 通过MCP工具调用
create_note(
    paragraphs=[
        {
            "texts": [
                {"text": "项目进展报告", "bold": true}
            ]
        },
        {
            "type": "quote",
            "texts": [
                {"text": "本周完成了主要功能开发，", "highlight": true},
                {"text": "详见技术文档", "link": "https://docs.example.com"}
            ]
        },
        {
            "type": "note",
            "note_id": "VPrWsE_-P0qwrFUOygGs8"
        },
        {
            "texts": [
                {"text": "下周计划：开始测试阶段"}
            ]
        }
    ],
    auto_publish=True,
    tags=["项目", "进展", "报告"]
)

Criar uma nota com arquivos

# 通过MCP工具调用
create_note(
    paragraphs=[
        {
            "texts": [
                {"text": "项目截图和演示", "bold": true}
            ]
        },
        {
            "type": "file",
            "file_type": "image",
            "source_type": "local",
            "source_path": "C:\\Users\\user\\Desktop\\screenshot.png",
            "metadata": {
                "alt": "项目主界面截图",
                "align": "center"
            }
        },
        {
            "texts": [
                {"text": "演示视频（音频）："}
            ]
        },
        {
            "type": "file",
            "file_type": "audio",
            "source_type": "url",
            "source_path": "https://example.com/demo.mp3",
            "metadata": {
                "show_note": "00:00 项目介绍\n01:30 功能演示\n03:00 总结"
            }
        },
        {
            "texts": [
                {"text": "详细文档见附件："}
            ]
        },
        {
            "type": "file",
            "file_type": "pdf",
            "source_type": "local",
            "source_path": "C:\\Users\\user\\Documents\\project_doc.pdf"
        }
    ],
    auto_publish=True,
    tags=["项目", "文档", "演示"]
)

Editar uma nota

# 通过MCP工具调用
edit_note(
    note_id="note_123456",
    paragraphs=[
        {
            "texts": [
                {"text": "更新：", "bold": true},
                {"text": "项目进度已完成80%"}
            ]
        },
        {
            "type": "quote",
            "texts": [
                {"text": "详细报告请查看：", "highlight": true},
                {"text": "项目文档", "link": "https://example.com/report"}
            ]
        },
        {
            "type": "note",
            "note_id": "related_note_id"
        }
    ]
)

Limites de cota da API

De acordo com a documentação da API da Mowen, cada interface tem os seguintes limites:

API	Cota	Limite de frequência	Descrição
Criação de notas	100 vezes/dia	1 vez/segundo	Conta apenas se a chamada for bem-sucedida, ou seja: você pode criar 100 notas por dia via API
Edição de notas	1000 vezes/dia	1 vez/segundo	Conta apenas se a chamada for bem-sucedida, ou seja: você pode editar 1000 vezes por dia via API
Configuração de notas	100 vezes/dia	1 vez/segundo	Conta apenas se a chamada for bem-sucedida

Estrutura do projeto

mowen-mcp-server/
├── src/
│   └── mowen_mcp_server/
│       ├── __init__.py       # 包初始化
│       ├── server.py         # MCP服务器主程序
│       └── config.py         # 配置管理
├── examples/
│   └── create_note/          # 创建笔记案例
├── pyproject.toml            # 项目配置
├── README.md                 # 项目文档
├── CHANGELOG.md              # 更新日志
└── 墨问API.md               # 墨问API详细文档

Documentação relacionada

Documentação online da API Mowen: https://mowen.apifox.cn/
Documentação local da API: consulte o arquivo 墨问API.md no projeto para obter a documentação detalhada da API Mowen
Documentação do protocolo MCP: Model Context Protocol

Perguntas frequentes

P: Por que o modo de módulo não funciona?

R: Certifique-se de ter instalado o pacote com pip install -e ., ou use o método de configuração com caminho direto do arquivo.

P: Onde obtenho a chave da API?

R: Faça login no miniaplicativo Mowen, encontre a chave da API no módulo de desenvolvedor da página pessoal. É necessário ter permissão de assinante Pro.

P: Posso editar notas criadas no miniaplicativo?

R: Atualmente não, apenas notas criadas via API podem ser editadas.

P: Como usar citações de parágrafos e notas com links internos?

R: Citações de parágrafos usam o formato {"type": "quote", "texts": [...]}, e notas com links internos usam o formato {"type": "note", "note_id": "笔记ID"}. Citações de parágrafos suportam todos os formatos de rich text (negrito, destaque, links).

P: De onde obtenho o note_id para notas com links internos?

R: O note_id é o ID da nota retornado ao criar a nota, ou o ID de uma nota existente na Mowen. Observe que só é possível referenciar notas criadas via API.

P: Por que só existe o parâmetro paragraphs, sem um parâmetro content simples?

R: Unificamos o design da interface; usar o formato de rich text permite suportar conteúdo mais rico. Mesmo para texto simples, é fácil usar o formato paragraphs: [{"texts": [{"text": "你的文本"}]}]

P: Como migrar de chamadas de API de versões antigas?

R: Se você usava create_note(content="文本") anteriormente, agora precisa mudar para create_note(paragraphs=[{"texts": [{"text": "文本"}]}]). Os recursos de rich text permanecem inalterados.

P: Por que recebo "arquivo não encontrado" ao fazer upload de arquivos?

R: É obrigatório usar caminho absoluto. O servidor MCP e o cliente são executados em diretórios de trabalho diferentes, e caminhos relativos falharão na resolução.

✅ Correto: "C:\\Users\\用户名\\Documents\\image.jpg" (Windows)
✅ Correto: "/Users/用户名/Documents/image.jpg" (macOS/Linux)
❌ Errado: "./image.jpg" ou "image.jpg" (caminhos relativos)

P: Quais tipos de arquivo são suportados?

R: Três tipos de arquivo são suportados:

Imagem (image): .gif, .jpeg, .jpg, .png, .webp (máximo de 50MB)
Áudio (audio): .mp3, .mp4, .m4a (máximo de 200MB)
PDF (pdf): .pdf (máximo de 100MB)

P: Quais são as limitações para upload de arquivos via URL remota?

R: URLs remotas não estão sujeitas a restrições de formato de caminho, mas o arquivo deve ser publicamente acessível e atender aos limites de tipo e tamanho de arquivo.

Contribuições para o desenvolvimento

Contribuições com Issues e Pull Requests são bem-vindas!

Configuração do ambiente de desenvolvimento

Clone o projeto
Instale as dependências de desenvolvimento: pip install -e .
Configure a variável de ambiente da chave da API
Execute os testes

Licença

Este projeto é licenciado sob a licença MIT. Consulte o arquivo LICENSE para obter detalhes.

Aviso legal

Este projeto é uma ferramenta de terceiros desenvolvida de forma independente e não tem relação oficial com a Mowen. Certifique-se de cumprir os termos de serviço da Mowen antes de usar.