monarch-mcp

Instructions

Implementation Reference

• src/monarch_mcp/server.py:191-212 (handler)

  The check_auth_status tool handler function that checks for authentication tokens in the keyring and environment variables, returning a status message about the current authentication state.

  @mcp.tool()
  def check_auth_status() -> str:
      """Check if already authenticated with Monarch Money."""
      try:
          # Check if we have a token in the keyring
          token = secure_session.load_token()
          if token:
              status = "Authentication token found in secure keyring storage\n"
          else:
              status = "No authentication token found in keyring\n"
  
          email = os.getenv("MONARCH_EMAIL")
          if email:
              status += f"Environment email: {email}\n"
  
          status += (
              "\nTry get_accounts to test connection or run login_setup.py if needed."
          )
  
          return status
      except Exception as e:  # pylint: disable=broad-exception-caught
          return f"Error checking auth status: {e}"

• src/monarch_mcp/server.py:191-191 (registration)

  The @mcp.tool() decorator that registers check_auth_status as an MCP tool with the FastMCP server instance.

  @mcp.tool()

• src/monarch_mcp/secure_session.py:36-47 (helper)

  The load_token() method in SecureMonarchSession class that retrieves the authentication token from the system keyring, which is called by check_auth_status to verify authentication state.

  def load_token(self) -> Optional[str]:
      """Load the authentication token from the system keyring."""
      try:
          token = keyring.get_password(KEYRING_SERVICE, KEYRING_USERNAME)
          if token:
              logger.info("Token loaded from keyring")
              return token
          logger.info("No token found in keyring")
          return None
      except Exception as e:  # pylint: disable=broad-exception-caught
          logger.error("Failed to load token from keyring: %s", e)
          return None

• src/monarch_mcp/secure_session.py:20-103 (helper)

  The SecureMonarchSession class that manages Monarch Money sessions securely using the system keyring, providing token storage, retrieval, and cleanup functionality used by check_auth_status.

  class SecureMonarchSession:
      """Manages Monarch Money sessions securely using the system keyring."""
  
      def save_token(self, token: str) -> None:
          """Save the authentication token to the system keyring."""
          try:
              keyring.set_password(KEYRING_SERVICE, KEYRING_USERNAME, token)
              logger.info("Token saved securely to keyring")
  
              # Clean up any old insecure files
              self._cleanup_old_session_files()
  
          except Exception as e:
              logger.error("Failed to save token to keyring: %s", e)
              raise
  
      def load_token(self) -> Optional[str]:
          """Load the authentication token from the system keyring."""
          try:
              token = keyring.get_password(KEYRING_SERVICE, KEYRING_USERNAME)
              if token:
                  logger.info("Token loaded from keyring")
                  return token
              logger.info("No token found in keyring")
              return None
          except Exception as e:  # pylint: disable=broad-exception-caught
              logger.error("Failed to load token from keyring: %s", e)
              return None
  
      def delete_token(self) -> None:
          """Delete the authentication token from the system keyring."""
          try:
              keyring.delete_password(KEYRING_SERVICE, KEYRING_USERNAME)
              logger.info("Token deleted from keyring")
  
              # Also clean up any old insecure files
              self._cleanup_old_session_files()
  
          except keyring.errors.PasswordDeleteError:
              logger.info("No token found in keyring to delete")
          except Exception as e:  # pylint: disable=broad-exception-caught
              logger.error("Failed to delete token from keyring: %s", e)
  
      def get_authenticated_client(self) -> Optional[MonarchMoney]:
          """Get an authenticated MonarchMoney client."""
          token = self.load_token()
          if not token:
              return None
  
          try:
              client = MonarchMoney(token=token)
              logger.info("MonarchMoney client created with stored token")
              return client
          except Exception as e:  # pylint: disable=broad-exception-caught
              logger.error("Failed to create MonarchMoney client: %s", e)
              return None
  
      def save_authenticated_session(self, mm: MonarchMoney) -> None:
          """Save the session from an authenticated MonarchMoney instance."""
          if mm.token:
              self.save_token(mm.token)
          else:
              logger.warning("MonarchMoney instance has no token to save")
  
      def _cleanup_old_session_files(self) -> None:
          """Clean up old insecure session files."""
          cleanup_paths = [
              ".mm/mm_session.pickle",
              "monarch_session.json",
              ".mm",  # Remove the entire directory if empty
          ]
  
          for path in cleanup_paths:
              try:
                  if os.path.exists(path):
                      if os.path.isfile(path):
                          os.remove(path)
                          logger.info("Cleaned up old insecure session file: %s", path)
                      elif os.path.isdir(path) and not os.listdir(path):
                          os.rmdir(path)
                          logger.info("Cleaned up empty session directory: %s", path)
              except Exception as e:  # pylint: disable=broad-exception-caught
                  logger.warning("Could not clean up %s: %s", path, e)