Joplin MCP Server

Instructions

Args:
    args: Import parameters
        file_path: Path to the markdown file

Returns:
    Dictionary containing the created note data

Implementation Reference

• src/mcp/joplin_mcp.py:233-270 (handler)

  The handler function for the 'import_markdown' tool, including the @mcp.tool() decorator for registration. It processes the input file path, parses the Markdown content using a helper utility, and creates a new note in Joplin.

  @mcp.tool()
  async def import_markdown(args: ImportMarkdownInput) -> Dict[str, Any]:
      """Import a markdown file as a new note.
      
      Args:
          args: Import parameters
              file_path: Path to the markdown file
      
      Returns:
          Dictionary containing the created note data
      """
      if not api:
          return {"error": "Joplin API client not initialized"}
      
      try:
          file_path = Path(args.file_path)
          md_content = MarkdownContent.from_file(file_path)
          
          note = api.create_note(
              title=md_content.title,
              body=md_content.content
          )
          
          return {
              "status": "success",
              "note": {
                  "id": note.id,
                  "title": note.title,
                  "body": note.body,
                  "created_time": note.created_time.isoformat() if note.created_time else None,
                  "updated_time": note.updated_time.isoformat() if note.updated_time else None,
                  "is_todo": note.is_todo
              },
              "imported_from": str(file_path)
          }
      except Exception as e:
          logger.error(f"Error importing markdown: {e}")
          return {"error": str(e)}

• src/mcp/joplin_mcp.py:57-60 (schema)

  Pydantic input schema for the import_markdown tool, defining the required 'file_path' parameter.

  class ImportMarkdownInput(BaseModel):
      """Input parameters for importing markdown files."""
      file_path: str

• src/joplin/joplin_utils.py:39-79 (helper)

  Helper classmethod MarkdownContent.from_file() that parses a markdown file, extracts title from first H1 or filename, and provides content, used directly in the import_markdown handler.

  @classmethod
  def from_file(cls, file_path: Path) -> 'MarkdownContent':
      """Create MarkdownContent from a file.
      
      Args:
          file_path: Path to the markdown file
          
      Returns:
          MarkdownContent instance
          
      Raises:
          FileNotFoundError: If the file doesn't exist
          ValueError: If the file is empty or invalid
      """
      if not file_path.exists():
          raise FileNotFoundError(f"File not found: {file_path}")
  
      if not file_path.is_file():
          raise ValueError(f"Not a file: {file_path}")
  
      content = file_path.read_text(encoding='utf-8')
      if not content.strip():
          raise ValueError(f"File is empty: {file_path}")
  
      # Extract title from first heading or use filename
      lines = content.splitlines()
      title = file_path.stem
  
      for line in lines:
          if line.startswith('# '):
              title = line[2:].strip()
              content = '\n'.join(lines[1:]).strip()
              break
  
      return cls(
          title=title,
          content=content,
          source_path=file_path,
          created_time=datetime.fromtimestamp(file_path.stat().st_ctime),
          modified_time=datetime.fromtimestamp(file_path.stat().st_mtime)
      )